Guides

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:

  1. Contact Integrations Support to ensure your merchant ID and account have access to a connection that supports full card information.

  2. 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.

  3. 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"
  }
}'



  4. In the response, check for success in the transactionStatus (of "pending" or "settled"). And save the recurringData.recurringId for use in subsequent transactions. You should also store the id 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 the transactionId. You can only get this parameter after the transaction runs. You get it in the webhook with the transactionId (note that this parameter is not returned for legacy webhooks) or in the id 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.

  1. Retrieve the recurringId you saved from the previous transaction.

  2. 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 a paymentOptionTag 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"
}'



  3. In the response, check for success in the transactionStatus (of "pending" or "settled"). And save the recurringData.recurringId (it may be different from the ID returned in the initial transaction) for use in subsequent transactions. You should also store the id 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 the transactionId. You can only get this parameter after the transaction runs. You get it in the webhook with the transactionId (note that this parameter is not returned for legacy webhooks) or in the id 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 2 months ago