OAPI checkout with Elavon Payment
This article is to explain how to map fields from an Elavon payment response to a checkout request using Appetize’s Ordering API. Third party Applications are responsible for integrating to Elavon’s checkout.js, this document explains how Elavon’s responses are mapped back to Appetize’s OAPI /checkout endpoint.
Example Request Payload sent to Elavon using Checkout Js library:
{
"fields":{
"ssl_txn_auth_token":"2ILqPlzDSAqSOKnOxBn/9AAAAXoK+DKA",
"ssl_card_number":"4111111111111111",
"ssl_exp_date":"12/23",
"ssl_first_name":"AA",
"ssl_last_name":"AA",
"ssl_cvv2cvc2":"0000",
"ssl_invoice_number":"3711274",
"ssl_avs_zip":"00000000"
}
}
· ssl_txn_auth_token Elavon session token
· ssl_invoice_number This field is not required by Elavon. However, Appetize requires this field in order to process future refunds. The application would be responsible for generating this invoice number. Appetize has a restriction of 7 characters. Users will not be able to refund in Appetize if this field is not populated with the seven digit number. This number is not forced unique by Elavon, or Appetize.
Example Successful Elavon payment Response:
{
"error":false,
"approved":true,
"dcc":false,
"threeDSecure":false,
"efs":false,
"fields":{
"ssl_merchant_initiated_unscheduled":"N",
"ssl_issuer_response":"00",
"ssl_last_name":"AA",
"ssl_partner_app_id":"01",
"ssl_card_number":"41**********1111",
"ssl_oar_data":"010012057306141441180000047554200000000000497727116514120573",
"ssl_result":"0",
"ssl_txn_id":"140621ED4-7BCB4327-D4C2-4533-9F6F-713FBD976657",
"ssl_avs_response":"N",
"ssl_approval_code":"497727",
"ssl_amount":"3.35",
"ssl_avs_zip":"00000000",
"ssl_txn_time":"06/14/2021 07:41:18 AM",
"ssl_exp_date":"1223",
"ssl_card_short_description":"VISA",
"ssl_get_token":"Y",
"ssl_token_response":"SUCCESS",
"ssl_card_type":"CREDITCARD",
"ssl_transaction_type":"SALE",
"ssl_account_balance":"0.00",
"ssl_ps2000_data":"A000000000000000 A",
"ssl_result_message":"APPROVAL",
"ssl_first_name":"AA",
"ssl_invoice_number":"3711274",
"ssl_cvv2_response":"P",
"ssl_token":"4432819799961111",
"ssl_add_token_response":"Card Updated"
},
"hashValue":"4783a113803be263ba31843f221cc1e7c64f15a99871e482dfb8734b10d37798",
"context":"MIIH6wYJKoZIhvcNAQcGoIIH3DCCB9gCAQAwggfRBgkqhkiG9w0BBwEwcAYKYIZIAYb9HgUBAzBiBBCkUZ+XLsNJurRSoKgdsjigDE5zZWN1cmVjY25Abm92YS5wcnY6MDcwMTAxMDAwMDAwWjplMmVlLmdsb2JhbC5wcnYjMTU4Nzc0NjMwMDpkYXRhOkFFUy1DQkM6MjU2OjqAggdQK+JnQNbhzSiV+92bG3jgp3mIooBMPYLSvINlFnFV1o9VJxAnx48tfcZJoLxuxGmbITM5icpd0DANuvdb4xw2LQ5volYpjGdM/KktdPS2UDuooRC46pf9IjKWuTe8z3Xcgpkq1gUQ83V1J3lFIU7sQm+MY8R0+fgLRs8vrOC0kZfJkHHaf71CrcoQh3gISiIXOQN",
"transactionTokenId":"2ILqPlzDSAqSOKnOxBn/9AAAAXoK+DKA"
}
Appetize Ordering API (OAPI) uses the following fields from Elavon’s payment response:
· ssl_txn_id: Unique identifier of the transaction.
· ssl_approval_code: Transaction Approval Code
· ssl_invoice_number: Invoice number
· ssl_token: Token previously generated from a credit card.
· ssl_transaction_type: Type of transaction
· ssl_exp_date:Card expiration date
· ssl_amount: Transaction amount
· ssl_card_short_description:Card type
Example Request Payload sent to OAPI /checkout
{
"payments":[
{
"amount":3.35,
"authorization_code":"",
"card_encoded":false,
"cardholder_fullname":"AA AA",
"cardholder_name":"AA AA",
"card_number":"4111111111111111",
"card_status":"cnp",
"card_type":"VISA",
"code_map":0,
"encryption_type":"cnp",
"exp_date":"1223",
"fee":0.21,
"payment_index":0,
"payment_status":"COMPLETED",
"payment_type":1,
"payment_valid":true,
"refunded":false,
"remaining_balance":0,
"subpayment_type":36,
"subtotal_amount":2.45,
"tax":0.25,
"tip":0.44,
"custom_tender_id":"",
"gateway_response_data":"",
"external_data":{
"card_art_cmid":"",
"auth_amount":"",
"auth_currency":"USD",
"auth_status_code":"",
"auth_code":"",
"balance":"",
"capture_method":"",
"card_class":"",
"card_status_code":"",
"card_token":"",
"card_type":"VISA",
"confirmation_code":0,
"device_transaction_id":"140621ED4-7BCB4327-D4C2-4533-9F6F-713FBD976657",
"receipt_identifier":{
"authorization_code":"497727"
},
"transaction_identifier":{
"local_request_id":"3711274",
"remote_request_id":"ID:4432819799961111",
"merchant_reference_code":"3711274",
"authorization_code":"497727",
"original_transaction_type":"SALE",
"expiration_date":"1223",
"current_total_amount":"3.35",
"account_token":"4432819799961111"
},
"invoice_number":"32fb6371-fd41-454a-a759-ecf42c26ce65",
"expiration_date":"",
"issuer_name":"",
"masked_acc":"",
"payment_gateway":"",
"req_amount":"",
"req_currency":"USD",
"transaction_type":"SALE",
"transaction_uid":"140621ED4-7BCB4327-D4C2-4533-9F6F-713FBD976657",
"entitlement_id":"",
"entitlement_type":"",
"payment_partner_data":null
},
"payment_uuid":"",
"payment_identifier_for_display":"",
"token_value":"",
"tender_name":"",
"ppi_loyalty_id":"",
"ppi_pin":""
}
],
"device_order_uuid":"e59ab199-d7ac-425b-8ad2-22fea01e708f",
"send_email_receipt":true
}
Detailed Information about fields sent to OAPI /checkout
· device_order_uuid UUID generated by /calculate cart endpoint
· send_email_receipt boolean to enable/disable email receipt
· payments payments array
o amount total amount for the payment
o authorization_code Application should send this as an empty string
o card_encoded Application should send this as CNP always
o cardholder_fullname cardholder full name or customer name
o cardholder_name cardholder full name or customer name
o card_number credit card number
o card_status Application should send this field as “CNP” Always.
o card_type card brand, Application should map this with ssl_card_short_description from Elavon response
o code_map Application should send this field as “0” always.
o encryption_type Application should send this as CNP
o exp_date cc expiration date
o fee calculated fee for the transaction
o payment_index Application should send the index of the payment array
o payment_status Application should send this field as “COMPLETE” always
o payment_type Application should send this as 1
o payment_valid Application should send this field as true
o refunded Application should send this this field as false
o remaining_balance Application should send this this field as 0 value
o subpayment_type Application should send this field as “36”
o subtotal_amount subtotal amount for the payment
o tax calculated tax for the transaction
o tip user’s tip
o custom_tender_id Application should send this this as an empty string
o gateway_response_data Application should send this this as an empty string
o external_data Application should use this field based on the payment type and maps a different payload. See Below
o payment_uuid Application should send this this as an empty string
o payment_identifier_for_display Application should send this this as empty string
o token_value Application should send this this as an empty string
o tender_name Application should send this this as an empty string
o ppi_loyalty_id Application should send this this as an empty string
o ppi_pin Application should send this this as an empty string
Detailed Information about fields sent to OAPI /checkout external_data object:
· card_art_cmid Application should send this this as an empty string
· auth_amount Application should send this this as an empty string
· auth_currency Application should send this this as USD always
· auth_status_code Application should send this this as an empty string
· auth_code Application should send this this as an empty string
· balance Application should send this this as an empty string
· capture_method Application should send this this as an empty string
· card_class Application should send this this as an empty string
· card_status_code Application should send this this as an empty string
· card_token Application should send this this as an empty string
· card_type card brand returned by Elavon, Application should map ssl_card_short_description from Elavon response
· confirmation_code Application should send this this as 0 value
· device_transaction_id Application should map ssl_txn_id from Elavon response
· receipt_identifier Map
o authorization_code Application should send this ssl_approval_code value from Elavon response
· transaction_identifier Map
o local_request_id Application should send this ssl_invoice_number value from Elavon response
o remote_request_id Application should send this ssl_token value from Elavon response
o merchant_reference_code Application should send this ssl_invoice_number value from Elavon response
o authorization_code Application should send this ssl_approval_code value from Elavon response
o original_transaction_type Application should send this ssl_transaction_type value from Elavon response
o expiration_date Application should send this ssl_exp_date value from Elavon response
o current_total_amount Application should send this ssl_amount value from Elavon response
o account_token Application should send this ssl_token value from Elavon response
· invoice_number
· expiration_date Application should send this this as an empty string
· issuer_name Application should send this this as an empty string
· masked_acc Application should send this this as an empty string
· payment_gateway Application should send this this as an empty string
· req_amount Application should send this this as an empty string
· req_currency Transaction currency, Application should send this this as USD
· transaction_type Application should send this this as an empty string
· transaction_uid Application should send this ssl_txn_id value from Elavon response
· entitlement_id Application should send this this as an empty string
· entitlement_type Application should send this this as an empty string
· payment_partner_data Application should send this this as null