3-D Secure
How Ginger Payments authenticates card payments with 3-D Secure 2
3-D Secure lets the card issuer authenticate the cardholder during an online card payment. When authentication succeeds, the liability for fraud-related chargebacks usually shifts from you to the card issuer.
Ginger Payments supports 3-D Secure 2 and handles it for you: the data exchange with the card schemes, the redirects and the result. You don't need a separate 3-D Secure integration.
Frictionless and challenge flow
The card issuer decides, based on the transaction data, which of two flows applies:
| Flow | What your customer sees |
|---|---|
| Frictionless | Nothing. The issuer authenticates the payment in the background. |
| Challenge | The issuer's authentication page, for example to approve the payment in a banking app or enter a one-time code. |
You don't choose the flow. The more complete the customer data in your order, such as name, email address, billing address and IP address, the more likely the issuer applies the frictionless flow.
- With the hosted payment page, authentication is part of the payment page.
- With a server-to-server integration, the authenticate request returns a
redirect_url. Redirect your customer to it. If a challenge is needed, it's shown there.
While your customer is authenticating, the transaction has the status pending. Afterwards your customer returns to your return_url. Always confirm the result with a status request or a webhook.
To test both flows, see Test data.
External 3-D Secure
If you already authenticate cardholders with your own 3-D Secure provider (MPI), you can send its results to Ginger Payments and skip authentication by Ginger Payments. This works with a server-to-server integration only.
Create the order and store the card
Follow the server-to-server flow: create the order with a credit-card transaction, and store the card in the vault to get a vault_token.
Authenticate with your provider
Run 3-D Secure authentication with your own provider and keep the values it returns.
Send the authentication values
Add the values to the authenticate request of the transaction:
curl https://api.dev.gingerpayments.com/v1/orders/$ORDER_ID/transactions/$TRANSACTION_ID/authenticate/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--data '{
"vault_token": "d972dc43-6a3d-4dcf-b54e-6e9a0fe325e3",
"cvc": "123",
"cavv": "jD8Ynh4EG+KCCBEFfTanAoQAAAA=",
"3ds_version": "2.2.0",
"3ds_method_used": "challenge",
"ds_transaction_id": "bcde185e-91a9-4e06-8fed-c733b11e00ad"
}'| Field | Required | Description |
|---|---|---|
cavv | Yes | Base64-encoded authentication value from your 3-D Secure provider. Visa and Mastercard use different underlying formats. |
3ds_version | Yes | 3-D Secure protocol version used: 2.1.0 or 2.2.0. |
3ds_method_used | Yes | Authentication flow used: challenge or frictionless. |
ds_transaction_id | Yes | Transaction ID assigned by the directory server (DS). |
The payment is processed directly with the values you sent. The order shows them under external_authentication_details:
{
"id": "6bf8a727-bef2-4420-8d41-af82f6f19f3d",
"currency": "EUR",
"amount": 100,
"description": "External 3-D Secure",
"status": "completed",
"transactions": [
{
"id": "59f5866a-c216-472e-b803-8a4e83c4578a",
"payment_method": "credit-card",
"payment_method_details": {
"card_expiry": "012030",
"external_authentication_details": {
"authenticationValue": "jD8Ynh4EG+KCCBEFfTanAoQAAAA=",
"dsTransID": "bcde185e-91a9-4e06-8fed-c733b11e00ad",
"methodUsed": "challenge",
"protocolVersion": "2.2.0"
},
"truncated_pan": "4111********1111",
"vault_token": "d972dc43-6a3d-4dcf-b54e-6e9a0fe325e3"
},
"status": "accepted"
}
]
}