Process an Authorization
POST /cardpayments/v1/accounts/account_id/auths
To process an authorization, you must initiate a POST request to the auths endpoint.
The settleWithAuth parameter should be set to false in the body of the request.
An amount is authorized (balance is held) on the card and a subsequent settlement (capture funds) request will be required to charge the customer and initiate transfer of funds to the merchant.
Split Payouts cannot be used in Authorizations that have settleWithAuth=false, where the intention is to settle the purchase later. In those situations, Split Payouts must be used in the settlement request. You can, however, use Split Payouts in purchases where authorization and settlement are combined (settleWithAuth=true).
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": "authonlydemo-1",
"amount": 10098,
"settleWithAuth": false,
"card": {
"cardNum": "4111111111111111",
"cardExpiry": {
"month": 2,
"year": 2027
}
},
"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 received.
- Provide a unique merchant reference number for each transaction.
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 max=99999999999 | Yes | This is the amount in minor units requested for this authorization. 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:
| |
| 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/6ce78961-5989-4c4b-ad68-5f5af506143e"
}
],
"id":"6ce78961-5989-4c4b-ad68-5f5af506143e",
"merchantRefNum":"authonlydemo-1",
"txnTime":"2014-05-05T12:28:20Z",
"status":"COMPLETED",
"amount":10098,
"availableToSettle":10098,
"card":{
"type":"VI",
"lastDigits":"1111",
"cardExpiry":{
"month":2,
"year":2027
}
},
"authCode":"118428",
"billingDetails":{
"street":"100 Queen Street West",
"city":"Toronto",
"state":"ON",
"country":"CA",
"zip":"M5H2N2"
},
"merchantDescriptor":{
"dynamicDescriptor":"Test",
"phone":"123-1234123"
},
"currencyCode":"CAD",
"avsResponse":"MATCH"
}
The response parameters not included in the initial request are described below:
| Element | Child Element | Type | Description |
|---|---|---|---|
| links | array of link objects | Contains a single self link which can be used to fetch details about this authorization | |
| id | string | This is the unique ID for the authorization operation. | |
| txnTime | string | This is the transaction time and date in UTC format. | |
| status | enum | This is the status of the authorization. Possible values are:
| |
| availableToSettle | integer max=99999999999 | This is the amount available to settle in minor units. If this value is 0 then 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 length=4 | 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. You can either send this information in the request or ask Paysafe Group to configure a default value for this parameter for your account. |
| 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. This is the currency of the merchant account specified in the account_id request URL parameter when this authorization was created. | |
| avsResponse | enum | This is the Address Verification Service (AVS) response from the card issuer:
The address in the billingDetails object in the initial authorization request is verified against the address the card issuer has on file for the card. |