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.

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).

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.

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"
          }
        } '

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 received.
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 are described below:

Value Type Description Example
id string Unique id for this authorization. e50e19a6-8edd-44ec-abc4-18d0a97d51d8
links array of link objects

Contains a single "self" link which can be used to fetch details about this authorization

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
amount integer 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. 10098
availableToSettle integer Amount available to settle in minor units. If this value is 0 then the authorization has been fully settled (captured) 10098
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 initial authorization request is verified against the address the card issuer has on file for the card.

MATCH
status enum

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.
COMPLETED
currencyCode string

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

USD

See our API Reference section for the full list of authorization operations and all possible response / request parameters.

Did you find this page useful?