Running a card transaction using full card information
Background |
---|
Before starting this tutorial, make sure you understand the following topics from the Quick start section:
|
Depending on your configuration, you may be able to send full card information when running an initial or subsequent transaction (rather than using a saved card token).
Warning
Sending full card numbers could increase your PCI scope.
Initial transaction
For the initial transaction, complete the following steps:
-
Contact Integrations Support to ensure your merchant ID and account have access to a connection that supports full card information.
-
Create a checkout page with your own form that has fields for the appropriate information from the customer, such as cardholder name, card number, expiration date, security code, and address.
-
On checkout, post payment details along with the full card information to the Run card transaction endpoint. See the endpoint reference for allowed parameters.
curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Basic [Base64_encoded_login]' -d '{ "data": { "amount": 29.99, "currency": "USD", "customer": { "customerRef": "RP006", "orderNumber": "210058A", "firstName": "John", "lastName": "Doe", "billToAddressOne": "2147 West Silverlake Drive", "billToAddressTwo": "Apt 42", "billToCity": "Scranton", "billToState": "PA", "billToPostal": "18503", "billToCountry": "US", "billToPhone": "1555555555", "email": "[email protected]" } }, "card": { "pan": 4111111111111111, "expirationMonth": "12", "expirationYear": "2028", "cardHolderName": "John H Doe", "securityCode": 927 }, "processingOptions": { "paymentType": "initialUnscheduled" } }'
-
In the response, check for success in the
transactionStatus
(of "pending" or "settled"). And save therecurringData.recurringId
for use in subsequent transactions. You should also store theid
returned in the response as this is the payment ID and you can use it to query the status of the transaction (using the View transaction by payment ID endpoint) within about a minute. You may also want to store thetransactionId
. You can only get this parameter after the transaction runs. You get it in the webhook with thetransactionId
(note that this parameter is not returned for legacy webhooks) or in theid
returned in any of the following endpoints:{ "id": "eyJuYW1lIjpiY2hlY2tvdXQiLCJtZXJjaGFudElkIjoiMTEwMDExIiwicmVmTnVtYmVyIjoicGF5X21laHIzcmVsZ2x4a2hpZ25jaDRyNHJmaGphIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9", "merchantId": "100038", "transactionDate": "2023-04-04T20:43:50.174Z", "authCode": "463090", "transactionStatus": "settled", "amount": 29.99, "transactionType": "sale", "currency": "USD", "gatewayResponse": { ... }, "data": { "amount": 29.99, "currency": "USD", "settlementCurrency": "USD", "customer": { "orderNumber": "210058A", "customerRef": "RP006", "firstName": "John", "lastName": "Doe", "email": "[email protected]", "billToAddressOne": "2147 West Silverlake Drive", "billToAddressTwo": "Apt 42", "billToCity": "Scranton", "billToState": "PA", "billToPostal": "18503", "billToCountry": "US", "billToPhone": "1555555555" } }, "card": { "cardNumber": "411111******1111", "expirationYear": "2025", "expirationMonth": "12", "cardHolder": "John H Doe" }, "kountResponse": { ... }, "recurringData": { "recurringId": "943353097252193", "recurringIdType": "networkTransactionId" }, "token": {} }
Subsequent transaction
You can send full card information in subsequent transactions, such as card-not-present situations or where the customer is not available for security code verification. In such cases, you must use the recurringId
from the response for the previous transaction.
-
Retrieve the
recurringId
you saved from the previous transaction. -
Post payment details along with the full card information and the
recurringId
to the Run card transaction endpoint. If you have multiple connections/gateways for your merchant account, you may need to also include apaymentOptionTag
so that the transaction get routed to the same gateway where the initial transaction was made. See the endpoint reference for allowed parameters.curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Basic [Base64_encoded_login]' -d '{ "data": { "amount": 19.99, "currency": "USD", "customer": { "customerRef": "RP006", "orderNumber": "230058A", "firstName": "John", "lastName": "Doe", "billToAddressOne": "2147 West Silverlake Drive", "billToAddressTwo": "Apt 42", "billToCity": "Scranton", "billToState": "PA", "billToPostal": "18503", "billToCountry": "US", "billToPhone": "1555555555", "email": "[email protected]" } }, "card": { "pan": 4111111111111111, "expirationMonth": "12", "expirationYear": "2028", "cardHolderName": "John H Doe" }, "processingOptions": { "paymentType": "scheduled", "paymentOptionTag": "usaepay" }, "recurringId": "858939643422519" }'
-
In the response, check for success in the
transactionStatus
(of "pending" or "settled"). And save therecurringData.recurringId
(it may be different from the ID returned in the initial transaction) for use in subsequent transactions. You should also store theid
returned in the response as this is the payment ID and you can use it to query the status of the transaction (using the View transaction by payment ID endpoint) within about a minute. You may also want to store thetransactionId
. You can only get this parameter after the transaction runs. You get it in the webhook with thetransactionId
(note that this parameter is not returned for legacy webhooks) or in theid
returned in any of the following endpoints:{ "id": "eyJuYW1lIjpiY2hlY2tvdXQiLCJtZXJjaGFudElkIjoiMTEwMDExIiwicmVmTnVtYmVyIjoicGF5X21laHIzcmVsZ2x4a2hpZ25jaDRyNHJmaGphIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9", "merchantId": "100038", "transactionDate": "2023-05-01T13:27:28.253Z", "authCode": "563061", "transactionStatus": "settled", "amount": 19.99, "transactionType": "sale", "currency": "USD", "gatewayResponse": { ... }, "data": { "amount": 19.99, "currency": "USD", "settlementCurrency": "USD", "customer": { "orderNumber": "230058A", "customerRef": "RP006", "firstName": "John", "lastName": "Doe", "email": "[email protected]", "billToAddressOne": "2147 West Silverlake Drive", "billToAddressTwo": "Apt 42", "billToCity": "Scranton", "billToState": "PA", "billToPostal": "18503", "billToCountry": "US", "billToPhone": "1555555555" } }, "card": { "cardNumber": "411111******1111", "expirationYear": "2025", "expirationMonth": "12", "cardHolder": "John H Doe" }, "kountResponse": { ... }, "recurringData": { "recurringId": "843253077222293", "recurringIdType": "networkTransactionId" }, "token": {} }
Updated 19 days ago