Search Overlay

Process a Card Purchase with 3D Secure 2

POST /cardpayments/v1/accounts/account_id/auths

Once the user has been authenticated and the authentication has been registered and validated on the Paysafe Group platform, you can do a regular POST request to the auths endpoint.

Your request must contain the additional JSON Authentication object.

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
},
"authentication": {
"eci": 5,
"cavv": "AAABCIEjYgAAAAAAlCNiENiWiV+=",
"threeDResult": "Y",
"threeDSecureVersion":"2.1.0",
"directoryServerTransactionId":"a3a721f3-b6fa-4cb5-84ea-c7b5c39890a2"
},
"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.

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 of the request, in minor units.
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
cvv

string
length=3-4

No This is the 3- or 4-digit security code that appears on the card following the card number.
authentication eci integer Yes This is the Electronic Commerce Indicator code, which gets returned by the card issuer, indicating whether the cardholder was successfully authenticated.
cavv string
length<=80
Yes This is the Cardholder Authentication Verification Value, which gets returned by the card issuer, indicating that the transaction has been authenticated.
threeDResult enum No

This indicates the outcome of the authentication. Possible values are:

  • Y – The cardholder successfully authenticated with their card issuer
  • A – The cardholder authentication was attempted
  • N – The cardholder failed to authenticate with their card issuer
  • U – Authentication with the card issuer was unavailable
  • E – An error occurred during authentication
  • R – Rejected transaction

The R value exists only for 3D Secure 2.

directoryServerTransactionId string
length<=36
No

This is the unique directory server transaction ID required for Mastercard.

This is field is required when the card issuer is Mastercard. This exists only for 3D Secure 2.

threeDSecureVersion string
min=5, max=8
Yes This is the 3D secure protocol version.
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
}
"authentication": {
"eci": 5,
"cavv": "AAABCIEjYgAAAAAAlCNiENiWiV+=",
"threeDResult": "Y",
"threeDSecureVersion":"2.1.0",
"directoryServerTransactionId":"a3a721f3-b6fa-4cb5-84ea-c7b5c39890a2"
},
"billingDetails": {
"street": "100 Queen Street West",
"city": "Toronto",
"state": "ON",
"country": "CA",
"zip": "M5H 2N2"
}
} '

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

Contains a settlement link which can be used to fetch details about the settlement (capture).

id   string
length<=36
This is the ID returned in the response.
txnTime  

string

UTC date format

This is the date and time the request was processed.
status   enum

The status of the authorization associated with this purchase. 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 an error or being declined.
  • CANCELLED – The request has been fully reversed.
availableToSettle   integer
max=99999999999
This is the amount of the Authorization remaining to settle, in minor units.
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.