PayPal
PayPal® eCommerce Customers
You can link your hosted payment page to your PayPal merchant account to offer another payment option to your buyers. These transactions process through the PayPal platform, but Converge will display the results and issue email receipts or confirmations.
If you already have a PayPal account, all you need to do is register your PayPal Payer ID in Converge to enable the feature.
If you don’t have an existing PayPal merchant account, you can register for one through Converge. You can find PayPal Registration and/or Activation in Converge at Settings > Payment Extensions, and in Classic at Terminal > Advanced > System Setup.
Once you enable this feature, customers who arrive at your hosted payment page will automatically see the option to pay with their PayPal account.
PayPal Express Checkout
This message format is used to process PayPal Express Checkout transactions.
note
Market Segment PayPal Express Checkout is available only for Internet based Terminals
PayPal Boarding and Enablement
- You must login to Converge and enable PayPal Express Checkout on your Terminal.
- You must set up your Bank Account information on PayPal to accept deposits after the transactions are settled.
PayPal Branding Guidelines You must adhere to the PayPal Branding guidelines.
PayPal Sale (pesale)
The pesale
is a transaction in which an authorization and transaction is entered into the unsettled batch (of Converge). This transaction is used to obtain real-time authorization for a PayPal Sale transaction.
note
The transaction will be authorized and settled on PayPal.
Request
Input Field Name | Description | Required |
---|---|---|
ssl_transaction_type | PayPal Express Checkout Sale (pesale ) | Y |
ssl_merchant_id | Converge ID as provided by Elavon. | Y |
ssl_user_id | Converge User ID as configured on Converge, case sensitive. | Y |
ssl_pin | Converge PIN as configured within Converge, case sensitive. | Y |
ssl_amount | Transaction Sale Amount. Number with 2 decimal places. This amount includes the Net amount and Sales Tax.
| Y |
ssl_invoice_number | The invoice or ticket number. | N |
ssl_description | The description, merchant defined value. | N |
ssl_customer_code | Recommended for purchasing cards. The Customer Code or PO Number that appears on the cardholder’s credit card billing statement. | N |
ssl_transaction_currency | Use only with a terminal that is set up with Multi-Currency. Transaction currency alphanumeric code must be included in the request to indicate the currency in which you wish to process. If omitted, the terminal default currency is assumed (for example: USD, CAD, and JPY). More than 25 currencies are supported and must be enabled on your PayPal Account before you can start using this feature. | |
ssl_product_string | Product string for PayPal transactions If submitted the line item products will be displayed to the Customer on the PayPal Express Checkout site. Multiple Products can be sent in this list in the format below:
| N |
ssl_eWallet_shipping | Wallet shipping option to indicate if the shipping address information used is retrieved from the PayPal website or the merchant’s website. Default is N. Valid values:
| N |
ssl_paypal_credit | If you are eligible to accept PayPal Credit, then you can send the PayPal Credit Option with your transaction request Valid value: Y = Show the PayPal Credit checkout flow to the buyer | N |
Response
Output Field Name | Description |
---|---|
ssl_result | Outcome of a transaction. A response that contains ssl_result of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized. |
ssl_result_message | Transaction result message. Example: APPROVAL, PARTIAL APPROVAL. Refer to the Payment Card Response Codes for an extensive list of possible returned messages. |
ssl_txn_id | Transaction identification number. This is a unique number used to identify the transaction. |
ssl_txn_time | Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. |
ssl_amount | The total transaction authorized or approved amount. This amount will include tip if tip has been provided in the request. Returned based on merchant setup. |
ssl_balance_due | Remaining balance due in the ssl_balance_due field. Thisis the difference of the amount requested versus the amount authorized that the merchant has to collect from the consumer on partial approvals only. |
ssl_invoice_number | The invoice or ticket number sent originally on the request. Returned based on merchant setup. |
ssl_transaction_currency | Transaction currency. Returned only if terminal is setup for Multi-Currency. |
errorCode | Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information. |
errorMessage | Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information. |
errorName | Error name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information. |
Examples
PayPal Express Checkout Auth Only (peauthonly
)
Use peauthonly
to get a real-time authorization for a PayPal Express Checkout transaction. This transaction will guarantee that the funds are available on the PayPal Account and reduce the cardholder’s limit to buy for a preset amount of time - usually 7-10 days based on the credit card’s issuing bank. However, when using peauthonly
, the authorization will not appear in the batch for settlement.
To place the transaction in the open batch, you must convert the authorization to Sale using cccomplete or reverse it using ccdelete
to restore the funds back to the card.
To place the transaction in the open batch, it must be converted to Sale using cccomplete
, or reversed using ccdelete
to restore the funds back to the card.
Input Field Name | Description | Required |
---|---|---|
ssl_transaction_type | PayPal Express Checkout Sale (peauthonly ) | Y |
ssl_merchant_id | Converge ID as provided by Elavon. | Y |
ssl_user_id | Converge User ID as configured on Converge, case sensitive. | Y |
ssl_pin | Converge PIN as configured within Converge, case sensitive. | Y |
ssl_amount | Transaction Sale Amount. Number with 2 decimal places. This amount includes the Net amount and Sales Tax.
| Y |
ssl_invoice_number | The invoice or ticket number. | N |
ssl_description | The description, merchant defined value. | N |
ssl_customer_code | Recommended for purchasing cards. The Customer Code or PO Number that appears on the cardholder’s credit card billing statement. | N |
ssl_salestax | Recommended for purchasing cards. Sales tax amount applied to this transaction in decimal. Tax exempt transactions can pass 0.00 to properly reflect a tax exempt transaction. | N |
ssl_transaction_currency | Use only with a terminal that is setup with Multi-Currency. Transaction currency alphanumeric code must be included in the request to indicate the currency in which you wish to process. If omitted, the terminal default currency is assumed (for example: USD, CAD, and JPY). More than 25 currencies are supported and must be enabled on your PayPal Account before you can start using this feature. | N |
ssl_product_string | Product string for PayPal transactions If submitted the line item products will be displayed to the Customer on the PayPal Express Checkout site. Multiple Products can be sent in this list in the format below:
| N |
ssl_eWallet_shipping | Wallet shipping option to indicate if the shipping address information used is retrieved from the PayPal website or the merchant’s website. Default is N. Valid values:
| N |
ssl_paypal_credit | If you are eligible to accept PayPal Credit, then you can send the PayPal Credit Option with your transaction request Valid value: Y = Show the PayPal Credit checkout flow to the buyer | N |
Response
Output Field Name | Description |
---|---|
ssl_result | Outcome of a transaction. A response that contains ssl_result of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized. |
ssl_result_message | Transaction result message. Example: APPROVAL, PARTIAL APPROVAL. Refer to the Payment Card Response Codes for an extensive list of possible returned messages. |
ssl_txn_id | Transaction identification number. This is a unique number used to identify the transaction. This value can be used to complete the Auth Only transaction. |
ssl_txn_time | Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. |
ssl_approval_code | Transaction approval code. |
ssl_amount | Transaction authorized or approved amount. Returned based on merchant setup. |
ssl_requested_amount | The amount originally requested on partial approvals only. |
ssl_balance_due | Remaining balance due in the ssl_balance_due field. Thisis the difference of the amount requested versus the amount authorized that the merchant has to collect from the consumer on partial approvals only. |
ssl_invoice_number | The invoice or ticket number sent originally on the request. Returned based on merchant setup. |
ssl_transaction_currency | Transaction currency. Returned only if terminal is setup for Multi-Currency. |
ssl_card_short_description | Card description, valid values are: AMEX, CUP, DISC, MC, PP, and VISA. |
ssl_card_type | Card type, valid values are: CASH, CREDITCARD, DEBITCARD, FOODSTAMP or GIFTCARD. |
errorCode | Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information. |
errorMessage | Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information. |
errorName | Error name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information. |
important
- In all of these examples, you will have to change the data values, such as
my_merchant_id
,my_user_id
,my_pin
, and transaction data to match your Converge account and meet the needs of your website. - Code samples provided are for demonstration only and should not be used for live transactions. All sensitive merchant data, including transaction amounts and your Converge credentials, should be placed in server side code, rather than in hidden value fields on an HTML form.
PayPal Express Checkout Return (pereturn)
The pereturn
transaction is used to issue a partial or a full return (refund) to a cardholder’s credit card using the Transaction ID of the original Sale or Force transaction. This will guarantee that the same credit card used previously for the purchase is the one being refunded.
Users may choose to generate a partial return by passing the original Transaction ID of the Sale or Force transaction and an amount that is less than the original amount, or a full return by passing the original Transaction ID only without the amount. Enhanced credits for an amount higher than the original Sale/Force amount are not allowed.
note
Converge will continue to allow merchants to refund credit card transactions using full card number/track data per current functionality using cccredit
. We strongly advise using the ccreturn
to reduce risks associated with refund abuse.
Request
Input Field Name | Description | Required |
---|---|---|
ssl_transaction_type | PayPal Express Checkout Credit (pereturn ) | Y |
ssl_merchant_id | Converge ID as provided by Elavon. | Y |
ssl_pin | Converge PIN as configured within Converge, case sensitive. | Y |
ssl_user_id | Converge User ID as configured on Converge, case sensitive. | Y |
ssl_txn_id | Unique identifier returned on the original transaction. | Y |
ssl_amount | Amount to be refunded in full or partial. Number with two decimal places. Must be less or equal to the original purchase, if not supplied original full amount is refunded. For example: 1.00. | N |
Response
Output Field Name | Description |
---|---|
ssl_result | Outcome of a transaction. A response that contains ssl_result of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized. |
ssl_result_message | Transaction result message. Example: APPROVAL. |
ssl_txn_id | Transaction identification number. This is a unique number used to identify the transaction. |
ssl_txn_time | Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. |
ssl_amount | Transaction authorized or approved amount. Returned based on merchant setup. |
ssl_approval_code | Transaction approval code. |
ssl_email | Returned based on merchant setup. |
ssl_invoice_number | The invoice or ticket number sent originally on the request. Returned based on merchant setup. |
errorCode | Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information. |
errorMessage | Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information. |
errorName | Error name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information. |
PayPal ExpressCheckout Void (pevoid)
The pevoid
is a transaction that removes a PayPal AUTH ONLY transaction from the open batch. No funds will deposit into the paypal bank account at settlement. The pevoid
command is typically used for same day returns or to correct cashier mistakes. You can only perform this action before the batch is settled. To perform a pevoid
, you must submit the Transaction ID received from the original transaction.
Request
Input Field Name | Description | Required |
---|---|---|
ssl_transaction_type | PayPal ExpressCheckout Void (pevoid ) | Y |
ssl_merchant_id | Converge ID as provided by Elavon. | Y |
ssl_user_id | Converge User ID as configured on Converge, case sensitive. | Y |
ssl_pin | Converge PIN as configured within Converge, case sensitive. | Y |
ssl_txn_id | Unique identifier returned on the original transaction. | Y |
Response
Output Field Name | Description |
---|---|
ssl_result | Outcome of a transaction. A response that contains ssl_result of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized. |
ssl_result_message | Transaction result message. Example: APPROVAL. |
ssl_txn_id | Transaction identification number. This is a unique number used to identify the transaction. |
ssl_txn_time | Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. |
ssl_email | Returned based on merchant setup. |
ssl_invoice_number | The invoice or ticket number sent originally on the request. Returned based on merchant setup. |
errorCode | Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information. |
errorMessage | Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information. |
errorName | Error name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information. |
PayPal Express Checkout Completion (pecomplete)
A transaction type of pecomplete
places an approved Auth Only transaction into the open batch for settlement.
You can convert an Auth Only transaction to a Sale by sending a pecomplete
transaction with a Transaction ID that belongs to an Auth Only transaction. All transactions converted to Sale will be placed in the open batch and are handled the same way as Sale transactions.
The following completion types are supported:
Full completion: Send
pecomplete
with the Auth Only Transaction ID without any amount, if you want to convert an existing Auth Only to Sale. The entire Auth Only transaction will move from the Auth Only batch to the Main batch for settlement.Partial-completion: Send
pecomplete
with the Auth Only Transaction ID with an amount that is less than the original Auth Only amount, if you wish to convert only a portion of the Auth Only to Sale. The Auth Only transaction will move from the Auth Only batch to the Main batch and the transaction will only be settled for smaller amount. You will not be able to use the original Auth Only transaction again.Multi partial-completion: Send
pecomplete
with the Auth Only Transaction ID with an amount that is less than the Auth Only amount and the Partial Shipment flag, this action will allow you to keep the unused portion of the Auth Only in the Auth Only batch, and convert only the selected portion to the Main batch. The Auth Only will remain in the Auth Only batch and you can perform multiple completions on the single Auth Only transaction until the total amount has been reached. Every completion will create a new fresh sale.
Request
Input Field Name | Description | Required |
---|---|---|
ssl_transaction_type | PayPal Express Checkout Completion (pecomplete ) | Y |
ssl_merchant_id | Converge ID as provided by Elavon. | Y |
ssl_user_id | Converge User ID as configured on Converge, case sensitive. | Y |
ssl_pin | Converge PIN as configured within Converge, case sensitive. | Y |
ssl_txn_id | Unique identifier returned on the original transaction. | Y |
ssl_amount | Amount to be refunded in full or partial. Number with two decimal places. Must be less or equal to the original purchase, if not supplied original full amount is refunded. For example: 1.00. | N |
ssl_partial_shipment_flag | Partial shipment flag to indicate the support of partial shipments, defaulted to N if not sent. Valid values:
| N |
Response
Output Field Name | Description |
---|---|
ssl_result | Outcome of a transaction. A response that contains ssl_result of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized. |
ssl_result_message | Transaction result message. Example: APPROVAL. |
ssl_txn_id | Transaction identification number. This is a unique number used to identify the transaction. |
ssl_txn_time | Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. |
ssl_amount | Transaction amount. Returned based on merchant setup. |
ssl_invoice_number | The invoice or ticket number sent originally on the request. Returned based on merchant setup. |
errorCode | Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information. |
errorMessage | Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information. |
errorName | Error name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information. |
Examples
Request
xmldata=
<txn>
<ssl_merchant_id>my_merchant_id</ssl_merchant_id>
<ssl_user_id>my_user_id</ssl_user_id>
<ssl_pin>my_pin</ssl_pin>
<ssl_description>Keyed Sale API</ssl_description>
<ssl_transaction_type>pecomplete</ssl_transaction_type>
<ssl_txn_id>AA4843B-EEBFF0FE-0BDC-47A3-B4F6-5D752E2FBE42</ssl_txn_id>
</txn>
Response
<txn>
<ssl_result>0</ssl_result>
<ssl_result_message>APPROVAL</ssl_result_message>
<ssl_txn_id>AA4843B-EEBFF0FE-0BDC-47A3-B4F6-5D752E2FBE42</ssl_txn_id>
<ssl_txn_time>07/21/2013 05:19:38 PM</ssl_txn_time>
<ssl_amount>3.00</ssl_amount>
<ssl_salestax>0.01</ssl_salestax>
<ssl_account_balance>0.00</ssl_account_balance>
<ssl_invoice_number>1234</ssl_invoice_number>
<ssl_first_name>John</ssl_first_name>
<ssl_last_name>Doe</ssl_last_name>
<ssl_avs_address>123 Main</ssl_avs_address>
<ssl_city>Atlanta</ssl_city>
<ssl_avs_zip>30123</ssl_avs_zip>
<ssl_state>GA</ssl_state>
<ssl_country>USA</ssl_country>
<ssl_dynamic_dba>123456789012*ABCCORP</ssl_dynamic_dba>
</txn>
Paypal with Checkout.js
To use Paypal with Checkout.js, you must take the following steps:
Include Converge Checkout.js and render a Paypal button on your page.
Prepare a session token.
Provide callback (as shown in the example code below).
<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<script src="https://api.demo.convergepay.com/hosted-payments/Checkout.js"></script>
<script>
var callback = {
onError: function (error) {
showResult("error", error);
},
onDeclined: function (response) {
showResult("declined", JSON.stringify(response));
},
onApproval: function (response) {
showResult("approval", JSON.stringify(response));
},
onCancelled: function () {
showResult("cancelled", "");
}
};
function initiatePayPal () {
var paymentFields = {
ssl_txn_auth_token: document.getElementById('transaction_session_token').value
};
ConvergeEmbeddedPayment.initPayPalCheckout('paypal-button', paymentFields, callback);
return false;
};
function showResult (status, msg) {
document.getElementById('txn_status').innerHTML = "<b>" + status + "</b>";
document.getElementById('txn_response').innerHTML = msg + "</b>";
};
</script>
</head>
<body>
<form>
Transaction Token: <input type="text" id="transaction_session_token"> <br><br>
<button onclick="return initiatePayPal();">Initiate PayPal</button> <br>
</form>
<br>
<div id="paypal-button"></div>
<br>
Transaction Status:<div id="txn_status"></div>
<br>
Transaction Response:<div id="txn_response"></div>
</body>
</html>