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.
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": "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
length<=255

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
length=8-20

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:

  • month – number, length=2
  • year – number, length=4
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.
Response Example
{
  "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:

  • 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.
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:

  • AM – American Express
  • DC – Discover
  • JC – JCB
  • MC – Mastercard
  • MD – Maestro
  • SO – Solo
  • VI – Visa
  • VD – Visa Debit
  • VE – Visa Electron
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
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.
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.

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:

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

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.

Did you find this page useful?