Search Overlay

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 \
-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


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

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.



No This indicates whether the request is an Authorization (no settlement) or a Purchase (authorization and settlement). The default value is false.
card cardNum


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
No This is the first line of the street address in the billing address.
city string
No This is the city in the billing address.
state string
No This is the state/province in the billing address.
country string
No This is the country in the billing address.
zip string
No This is the zip/postal code in the billing address.

"street":"100 Queen Street West",

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
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
This is the last four digits of the card used for the request.
authCode   string
This is the authorization code returned by the issuing bank.
merchantDescriptor dynamicDescriptor


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.


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 Group to configure a default value for this parameter for your account.

currencyCode   string

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.

On this Page