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 Group 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 settleWithAuth flag 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.
See our full API documentation for a complete description of the parameters required for the Authorization request.
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"
}
} '
By default, the card processing system will check for duplicate transactions.
Prior to trying the example, you should:
- 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.
- Provide a unique merchant reference number for each transaction.
The amount is specified in minor units of the currency of the merchant account defined 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.
The request contains the following parameters:
| Element | Child Element | Type | Required? | Description |
|---|---|---|---|---|
| merchantRefNum | string | Yes | This is the merchant reference number created by the merchant and submitted as part of the request. A unique merchant reference number must be provided for each transaction. | |
| amount | integer | Yes | This is the amount of the request, in minor units. Use the correct minor units amount for the account currency. 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. | |
| settleWithAuth | boolean | No | This indicates whether the request is an Authorization (no settlement) or a Purchase (authorization and settlement). The default value is false. | |
| card | cardNum | string | Yes | This is the card number used for the request. |
| cardExpiry | object | Yes | This is the card's expiry date. The following parameters are required:
| |
cvv | string length=3-4 | No | This is the 3- or 4-digit security code that appears on the card following the card number. | |
| billingDetails | street | string length<=50 | No | This is the first line of the street address in the billing address. |
| city | string length<=40 | No | This is the city in the billing address. | |
| state | string length<=40 | No | This is the state/province in the billing address. | |
| country | string length=2 | No | This is the country in the billing address. | |
| zip | string length<=10 | No | This is the zip/postal code in the billing address. |
{
"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 or the id returned in the response.
The response parameters not contained in the request are described below:
| Element | Child Element | Type | Description |
|---|---|---|---|
| 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. | |
| id | string length<=36 | Unique ID for this purchase operation. This ID can be used to look up the result of the authorization and settlement (capture) associated with this purchase. | |
| txnTime | string | This is the transaction time and date in UTC format. | |
| status | enum | The status of the authorization associated with this purchase. Possible values are:
| |
| availableToSettle | integer max=99999999999 | This is the amount remaining to settle. The merchant should verify that this value is 0 to confirm that the authorization has been fully settled (captured). | |
| card | type | enum | This is the type of card used in the request. Possible values are:
|
| lastDigits | string | This is the last four digits of the card used for the request. | |
| authCode | string length<=50 | This is the authorization code returned by the issuing bank. | |
| merchantDescriptor | dynamicDescriptor | string | This is a merchant descriptor that will be displayed on a customer’s card statement. |
| phone | string | This is the merchant’s phone number, which will be appended to the merchant descriptor on a customer’s card statement. | |
| currencyCode | string length=3 | This is the three-digit currency code of the merchant account specified in the account_id request URL parameter account_id. | |
| avsResponse | enum | This is the Address Verification Service (AVS) response from the card issuer:
The address in the billingDetails object in the request is verified against the address the card issuer has on file for the card. | |
| settlements | links | array of link objects | This parameter contains a single self link which can be used to fetch details about the settlement (capture). |
| id | string length<=36 | This is the unique ID for the settlement (capture). This ID can be used to look up the settlement details. | |
| merchantRefNum | string length<=255 | This is the merchant reference number. | |
| txnTime | string | This is the transaction time and date in UTC format. | |
| status | enum | The status of the settlement. Possible values are:
| |
| amount | integer max=99999999999 | This is the amount settled in minor units. | |
| availableToRefund | integer max=99999999999 | This is the amount in minor units available for refunding. The availableToRefund parameter will be 0 if the settlement failed (status=FAILED). If the settlement succeeds, it will be the same as the amount. |
Purchase Message Sequence
