Process a Purchase

POST /cardpayments/v1/accounts/account_id/auths

This API request verifies that a customer's account is valid and that sufficient funds are available to cover the transaction's cost. The funds are "held" and deducted from the customer's credit limit (or bank balance, in the case of a debit card) but are not yet transferred to the merchant. At the end of the day, Paysafe submits the PENDING settlements to the acquirer in a batch transfer, which begins the settlement process.

The funds are transferred from the customer's account to the merchant's account and the transaction may not appear on the customer's statement or online account activity for one to two days; it can take up to three business days for funds to be deposited in the merchant's account.

To process a purchase, you must initiate a POST request to the auths endpoint.

By default, an amount is authorized on the card and a subsequent settlement request is required to actually charge the customer. However, by setting the flag settleWithAuth to true, the card processing system automatically charges the card as part of the same request. To apply Split Payouts functionality, you must set this flag to true.

If you are shipping physical items, you should use the default setting to authorize the purchase before charging the card, and only perform the settlement once the items are actually shipped.

Request Example
curl -X POST https://api.test.paysafe.com/cardpayments/v1/accounts/89987201/auths \
  -u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc6712d0214736abf501e9675e55940e83ef77f5c304edc7968 \
  -H 'Content-Type: application/json' \
  -d ' {
         "merchantRefNum" : "demo-1",
         "amount" : 10098,
         "settleWithAuth":true,
         "card" : {
           "cardNum" : "4111111111111111",
           "cardExpiry":{
             "month":2,
             "year":2027
            },
            "cvv":123
          },
          "billingDetails":{
             "street":"100 Queen Street West",
             "city":"Toronto",
             "state":"ON",
             "country":"CA",
             "zip":"M5H 2N2"
          }
        } '

The amount is specified in minor units of the currency of the merchant account specified using the account_id URL parameter. For example, to process US $10.99, this value should be 1099. To process 1000 Japanese yen, this value should be 1000. To process 10.139 Tunisian dinar, this value should be 10139.

By default the card processing system will check for duplicate transactions.

Prior to trying the example, you should:

  • Provide a unique merchant reference number for each transaction.
  • Replace the account number (89987201) in the URL with the test account number you received.
  • Replace the API key (after the -u) with the API key you have received.
Response Example
{
  "links":[
    {
      "rel":"self",
      "href":"https://api.test.paysafe.com/cardpayments/v1/accounts/89987201/auths/ebf6ae3d-88e1-40da-9b98-81044467345b"
    },
    {
      "rel":"settlement",
      "href":"https://api.test.paysafe.com/cardpayments/v1/accounts/89987201/settlements/ebf6ae3d-88e1-40da-9b98-81044467345b"
    },
 ],
  "id":"ebf6ae3d-88e1-40da-9b98-81044467345b",
  "merchantRefNum":"demo-1",
  "txnTime":"2017-05-01T14:52:35Z",
  "status":"COMPLETED",
  "amount":10098,
  "settleWithAuth":true,
  "availableToSettle":0,
  "card":{
    "type":"VI",
    "lastDigits":"1111",
    "cardExpiry":{
      "month":2,
      "year":2027
    }
  },
  "authCode":"114974",
  "billingDetails":{
    "street":"100 Queen Street West",
    "city":"Toronto",
    "state":"ON",
    "country":"CA",
    "zip":"M5H2N2"
  },
  "merchantDescriptor":{
    "dynamicDescriptor":"Test",
    "phone":"123-1234123"
  },
  "currencyCode":"CAD",
  "avsResponse":"MATCH",
  "settlement" : {
    "links": [
      {
        "rel": "self",
        "href": "https://api.test.paysafe.com/cardpayments/v1/accounts/89987201/settlements/ebf6ae3d-88e1-40da-9b98-81044467345b"
      }
    ],
    "id": "ebf6ae3d-88e1-40da-9b98-81044467345b",
    "merchantRefNum": "demo-1",
    "txnTime": "2017-05-01T14:52:35Z",
    "status": "PENDING",
    "amount": 10098,
    "availableToRefund": 0
  }
 }

The status is set to COMPLETED and the value for availableToSettle is 0 because the card was automatically charged as part of the request, since the settleWithAuth flag was set to true. You can look up the transaction at any future time using either the merchantRefNum (demo-1) or the id returned in the response (in this case - ebf6ae3d-88e1-40da-9b98-81044467345b).

The response parameters not contained in the request are described below:

Value Type Description Example
id string Unique id for this purchase operation. This ID can be used to look up the result of the auth and settlement (capture) associated with this purchase e50e19a6-8edd-44ec-abc4-18d0a97d51d8
links array of link objects

Contains a "self" link which can be used to fetch details about the authorization for this purchase.

Contains a "settlement" link which can be used to fetch details about the settlement (capture) associated with this purchase.

card/type enum

The type of card used in the request. Possible values are:

  • AM – American Express
  • DC – Discover
  • JC – JCB
  • MC – Mastercard
  • MD – Maestro
  • SO – Solo
  • VI – Visa
  • VD – Visa Debit
  • VE – Visa Electron
VI
card/lastDigits string Returns the last four digits of the card used in the request 1111
authCode string This is the Authorization code returned by the issuing bank 026189
txnTime string Transaction time and date in UTC format 2013-12-14T15:12:18Z
availableToSettle integer Amount remaining to settle. The merchant should check this value is 0 to confirm the authorization has been fully settled (captured) 0
merchantDescriptor/dynamicDescriptor

string

length<=20

This is a merchant descriptor that will be displayed on a customer’s card statement. You can either send this information in the request or ask Paysafe to configure a default value for this parameter for your account. OnlineStore
merchantDescriptor/phone

string

length<=13

This is the merchant’s phone number, which will be appended to the merchant descriptor on a customer’s card statement.

You can either send this information in the request or ask Paysafe to configure a default value for this parameter for your account.

12345678
avsResponse enum

Address Verification Service Response from the card issuer:

  • MATCH
  • MATCH_ADDRESS_ONLY
  • MATCH_ZIP_ONLY
  • NO_MATCH
  • NOT_PROCESSED
  • UNKNOWN

The address in the billingDetails object in the request is verified against the address the card issuer has on file for the card.

MATCH
cvvVerification enum

This is the response to the cvv submitted with the transaction request. Possible values are:

  • MATCH
  • NO_MATCH
  • NOT_PROCESSED
  • UNKNOWN
MATCH
status enum

The status of the authorization associated with this purchase. Possible values are:

  • RECEIVED – Our system has received the request and is waiting for the downstream processor’s response.
  • COMPLETED – The transaction has been completed.
  • HELD – The transaction has been placed on hold due to risk considerations.
  • FAILED – The transaction failed, due to either an error or being declined.
  • CANCELLED – The request has been fully reversed.
COMPLETED
currencyCode string

Three digit currency code. This is the currency of the merchant account specified in the account_id request URL parameter account_id.

USD
settlements array of settlement objects Contains a single settlement object

The settlement object response contains the following obligatory parameters:

Value Type Description Example
id string Unique id for the settlement (capture). This ID can be used to look up the settlement details e50e19a6-8edd-44ec-abc4-18d0a97d51d8
links array of link objects

Contains a single "settlement" link which can be used to fetch details about the settlement (capture)

txnTime string Transaction time and date in UTC format 2013-12-14T15:12:18Z
amount integer amount settled in minor units 10098
availableToRefund integer Amount in minor units available for refunding. Available to refund will be 0 if the settlement failed (status=FAILED). If the settlement succeeds, it will be the same as the amount. 10098
status enum

The status of the settlement. Possible values are:

  • RECEIVED – Our system has received the request and is waiting for the downstream processor’s response.
  • PENDING – Our system has received the request but it has not yet been batched.
  • PROCESSING – The Settlement batch has started.
  • COMPLETED – The transaction has been completed.
  • FAILED – The transaction failed, due to either an error or being declined.
  • CANCELLED – The transaction request has been cancelled.
COMPLETED

See our API Reference section for a list of all the JSON attributes and types available for the Authorization endpoint.

Purchase Message Sequence

Did you find this page useful?