> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paybyrd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Card

This page explains how to accept card payments using the Paybyrd API.

## Overview

Paybyrd handles the complexity of card payment processing, including 3D Secure authentication. By default, the API triggers the 3D Secure V2 flow for all card transactions, with a native fallback to V1 if the card is not enrolled for V2. No additional development is required on your side to support both versions. A single request is enough to enable SCA (Strong Customer Authentication) and process payments in a secure environment.

<Info>**PCI compliance:** In case you are not PCI compliant and you want to build your own cards payment form, please check our hosted form and card collect solution.</Info>

## 3D Secure

3D Secure (3DS) is a security layer that provides fraud prevention for card payments. The system requires customers to complete an additional verification step with the card issuer when paying. It involves a pop-up window or inline frame appearing during the online transaction process, requiring the cardholder to authenticate the card, typically by entering a password or a code sent to their phone.

Paybyrd triggers 3D Secure for all transactions by default. To create a transaction without 3D Secure, set the parameter `VerificationMethod=None`. Note that the card issuer will likely decline such transactions.

## Paybyrd API and 3D Secure server-side

The card payment creation is divided mainly in three steps:

1. Creation of the card payment
2. 3D Secure authentication
3. Payment completion (optional)

### Creation of the card payment

On the first step you will need to create the payment and provide all the necessary information for the next steps. Paybyrd has two different flows that can be triggered depending on the parameters you sent to us. In the first flow, Paybyrd handles the 3D Secure authentication result and calls the payment completion automatically. To use this flow, provide the `RedirectUrl` parameter. Paybyrd redirects the customer to this URL after the full process completes. You can use that page to query the transaction status and direct the shopper accordingly.

You can see below an example of how to create a card payment that will trigger the 3D Secure flow which will be fully managed by Paybyrd:

<CodeGroup>
  ```bash Card Payment and Redirect URL Request theme={null}
  curl --request POST \
   --url https://gateway.paybyrd.com/api/v2/payment \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json' \
   --header 'x-api-key: {your_api_key}' \
   --data '
  {
   "type": "Card",
   "amount": "8.15",
   "currency": "EUR",
   "orderRef": "ABC12345",
   "redirectUrl": "https://your-shop-url?orderRef=ABC12345",
   "card": {
     "number": "4200000000000000",
     "expiration": "02/25",
     "cvv": "123",
     "holder": "Peter Parker"
   }
  }'
  ```

  ```json Card Payment and Redirect URL Response theme={null}
  {
   "transactionId": "0e443bff-9052-4eec-a5f1-9db474f2077a",
   "type": "Card",
   "currency": "EUR",
   "orderRef": "ABC12345", 
   "brand": "VISA",
   "fingerprint": "b53b68c8-43af-4acc-bc79-e892dd6a9a38",
   "amount": "8.15",
   "isPreAuth": false,
   "redirectUrl": "https://your-shop-url?orderRef=ABC12345",
   "action": {
     "type": "redirect",
     "url": "https://link-s.paybyrd.com/3ds_Q44clBT77"
   },
   "card": {
     "number": "420000******0000",
     "expiration": "12/25",
     "cvv": "***",
     "holder": "Peter Parker"
   },
   "code": "BYRD207",
   "description": "Pending redirect"
  }
  ```
</CodeGroup>

### Soft descriptor

You can customize the text shown on the cardholder's bank statement for each transaction by passing a `softDescriptor` value in the payment request. This is useful for providing a clearer transaction reference to your customers.

The field accepts a string of up to 22 characters. Requests exceeding this limit return `400 Bad Request`.

```json theme={null}
{
  "type": "Card",
  "softDescriptor": "Paybyrd Store Purchase",
  ...
}
```

### Using callbacks in the 3DSecure flow

To handle the 3D Secure result yourself, provide the `CallbackUrl` inside the `ThreeDSecure` node instead of the `RedirectUrl` parameter. Paybyrd sends the authentication result to that URL as a base64-encoded query parameter. You can decode it, review the result, and decide whether to call the payment completion. This is useful if you need to run anti-fraud checks before completing the transaction.

You can see below an example of how to create a card payment that will trigger the 3D Secure flow which will be managed by you:

<CodeGroup>
  ```bash Card Payment and 3DSecure Callback URL Request theme={null}
  curl --request POST \
   --url https://gateway.paybyrd.com/api/v2/payment \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json' \
   --header 'x-api-key: {your_api_key}' \
   --data '
  {
   "type": "Card",
   "amount": "8.15",
   "currency": "EUR",
   "orderRef": "ABC12345",
   "card": {
     "number": "4200000000000000",
     "expiration": "02/25",
     "cvv": "123",
     "holder": "Peter Parker"
   },
   "threeDSecure": {
     "callbackUrl": "https://your-threedsresult-handle-url.com"
   }
  }'
  ```

  ```json Card Payment and 3DSecure Callback URL Response theme={null}
  {
   "transactionId": "0e443bff-9052-4eec-a5f1-9db474f2077a",
   "type": "Card",
   "currency": "EUR",
   "orderRef": "ABC12345", 
   "brand": "VISA",
   "fingerprint": "b53b68c8-43af-4acc-bc79-e892dd6a9a38",
   "amount": "8.15",
   "isPreAuth": false,
   "action": {
     "type": "redirect",
     "url": "https://link-s.paybyrd.com/3ds_Q44clBT77"
   },
   "card": {
     "number": "420000******0000",
     "expiration": "12/25",
     "cvv": "***",
     "holder": "Peter Parker"
   },
   "threeDSecure": {
     "callbackUrl": "https://your-threedsresult-handle-url.com"
   },
   "code": "BYRD207",
   "description": "Pending redirect"
  }
  ```
</CodeGroup>

See the [full API reference](/api-reference/payments/create-payment) for more details.

Check the `code` field to know whether the transaction was accepted. A successful scenario returns the code `BYRD207` and `Pending redirect` in the `description` field. You can find the list of all status codes in the [Respone code reference](/api-reference/api-code-reference).

The `action` field contains the next step.

If you use your own 3D Secure provider and perform cardholder authentication before calling the Paybyrd API, provide the authentication data in your request. Paybyrd will respond with code `BYRD200` and no extra step is required. Please check the Using an external 3D Secure provider section.

### 3D Secure authentication

Once the shopper is redirected, Paybyrd triggers the 3D Secure authentication flow. A challenge may be presented, in which case the bank screen will wait for the shopper to authenticate. In case you provided the `RedirectUrl` parameter during the first step, the payment will be processed automatically right after the 3D Secure authentication and the shopper will be redirected to the URL sent.

For the scenario where you sent the `CallbackUrl` instead, we will call the provided URL with the `threeDSecureResult` parameter encoded in base64 as you can see below:

```
http://your-threedsresult-handle-url.com/?threedSecureResult=eyJ0cmFuc2FjdGlvbklkIjoiMjgzMjlmNjEtNDE2NC00MGQwLWI5MzktZmUxMjk3ZTlmOTE2Iiwic3RhdHVzIjoiQXV0aG9yaXplZCIsImF1dGhlbnRpY2F0aW9uRGF0YSI6eyJ0aHJlZURzVmVyc2lvbiI6IlYyIiwiYWF2IjoiZjVkZjQwMDdjODQ3NDZhZTgwNjU1ODM2OTViOGJjYTUiLCJkc1RyYW5zYWN0aW9uSWQiOiI1ZTRiZjA3Zi03NDBjLTQ4YmMtYjI5Ni02YjA5NWEyOTQzZjkiLCJlY2kiOiIwNSIsInZlcmlmaWNhdGlvbk1ldGhvZCI6IlRocmVlRFNlY3VyZSJ9LCJ0cmFuc1N0YXR1cyI6IlkiLCJ0cmFuc1N0YXR1c1JlYXNvbiI6IjE3In0
```

The decoded response will look like the following json:

<CodeGroup>
  ```json Authorized theme={null}
  {
   "transactionId": "28329f61-4164-40d0-b939-fe1297e9f916",
   "status": "Authorized",
   "authenticationData": {
     "threeDsVersion": "V2",
     "aav": "f5df4007c84746ae8065583695b8bca5",
     "dsTransactionId": "5e4bf07f-740c-48bc-b296-6b095a2943f9",
     "eci": "05",
     "verificationMethod": "ThreeDSecure"
   },
   "transStatus": "Y",
   "transStatusReason": "17"
  }
  ```

  ```json Unauthorized theme={null}
  {
   "transactionId": "5051e95a-977e-4925-a9af-3f05ce39c890",
   "status": "Unauthorized",
   "authenticationData": {
     "threeDsVersion": "V2",
     "dsTransactionId": "2b771583-f9a4-4562-a71d-badab879d7d7",
     "eci": "07",
     "verificationMethod": "ThreeDSecure"
   },
   "message": "Authorization failed",
   "details": "Security failure",
   "transStatus": "N",
   "transStatusReason": "09"
  }
  ```

  ```json NotEnrolled theme={null}
  {
   "transactionId": "0160b04d-61b4-47ce-bbf9-067bc939f0e5",
   "status": "NotEnrolled",
   "authenticationData": {
     "threeDsVersion": "V1",
     "eci": "06",
     "verificationMethod": "None"
   },
   "code": "999",
   "message": "Simulated not enrolled error",
   "details": "Simulated not enrolled error"
  }
  ```
</CodeGroup>

| Field                                 | Description                                                                                                                                                                                                                |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| TransactionId                         | Transaction id generated by Paybyrd                                                                                                                                                                                        |
| Status                                | `Authorized` — Authentication succeeded. `Unauthorized` — Authentication was declined. `NotEnrolled` — Card is not enrolled for 3D Secure.                                                                                 |
| AuthenticationData.ThreeDsVersion     | V2 / V1                                                                                                                                                                                                                    |
| AuthenticationData.Aav                | Authentication value received by the 3DS provider                                                                                                                                                                          |
| AuthenticationData.DsTransactionId    | Transaction id in the directory server                                                                                                                                                                                     |
| AuthenticationData.ECI                | Response code returned by the schemes                                                                                                                                                                                      |
| AuthenticationData.VerificationMethod | ThreeDSecure - Card went through the 3D Secure process. ThreeDSecureAttempt - Attempt (proof of authentication attempt, may continue to transaction but issuer might still reject). None - No authentication was performed |
| Code                                  | Error code                                                                                                                                                                                                                 |
| Message                               | Error message                                                                                                                                                                                                              |
| Details                               | Error message details                                                                                                                                                                                                      |
| TransStatus                           | Transaction status returned by ACS                                                                                                                                                                                         |
| TransStatusReason                     | Transaction status reason returned by ACS                                                                                                                                                                                  |

## Payment completion (optional)

After obtaining the 3D Secure response, call the Payment API to finalize the payment. Provide the card data and the 3D Secure information received during the previous step:

<CodeGroup>
  ```bash Request theme={null}
  curl --location --request POST 'https://gateway.paybyrd.com/api/v2/payment/0e443bff-9052-4eec-a5f1-9db474f2077a/pay' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: {your_api_key}' \
  --data '{
      "card":{
          "number":"4200000000000000",
          "expiration":"12/25",
          "cvv":"123",
          "holder":"Jane Jones",
          "threeDsVersion": "V2",
          "aav": "aaaaaaec781048dd9ad8fc96e0031111",
          "dsTransactionId": "11111111-1111-1111-1111-111111111111",
          "eci": "01",
          "verificationMethod": "ThreeDSecure"
      }
  }'
  ```

  ```json Response theme={null}
  {
      "code": "BYRD200",
      "description": "Operation successfully completed",
      "status": "Success"
  }
  ```
</CodeGroup>

## 3DS exemptions

If 3DS validation fails and you still want to proceed with the payment, provide the `threeDSecureExemption` field, which accepts the values `TRA` and `LowValue`.

```bash theme={null}
curl --location --request POST 'https://gateway.paybyrd.com/api/v2/payment/0e443bff-9052-4eec-a5f1-9db474f2077a/pay' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '{
    "card":{
        "number":"4200000000000000",
        "expiration":"12/25",
        "cvv":"123",
        "holder":"Jane Jones",
        "threeDsVersion": "V2",
        "dsTransactionId": "11111111-1111-1111-1111-111111111111",
        "eci": "07",
        "verificationMethod": "ThreeDSecure",
        "threeDSecureExemption": "TRA"
    }
}'
```

## Using an external 3D Secure provider

If you use an external 3DS server to authenticate the cardholder, pass the authentication data to the API when creating the payment:

<CodeGroup>
  ```bash Card 3DS V2 request theme={null}
  curl --request POST \
    --url https://gateway.paybyrd.com/api/v2/payment \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: {your_api_key}' \
    --data '{
    "type": "Card",
    "amount": "8.15",
    "currency": "EUR",
    "orderRef": "ABC12345",
    "card": {
      "number": "4200000000000000",
      "expiration": "02/25",
      "cvv": "123",
      "holder": "Peter Parker",
      "eci": "05",
      "aav": "avv123456abcd",
      "dsTransactionId": "33cdebf1-ff0c-4e33-a4b1-47e4c141fe58",
      "threeDSVersion": "V2",
      "verificationMethod": "ThreeDSecure"
    }
  }'
  ```

  ```json Card 3DS V2 Success response theme={null}
  {
      "type": "Card",
      "currency": "EUR",
      "orderRef": "ABC12345",
      "brand": "MASTER",
      "fingerprint": "b53b68c8-43af-4acc-bc79-e892dd6a9a38",
      "code": "BYRD200",
      "description": "Operation successfully completed",
      "transactionId": "0e443bff-9052-4eec-a5f1-9db474f2077a",
      "amount": "8.15",
      "isPreAuth": false,
      "card": {
          "number": "4200000000000000",
          "expiration": "02/25",
          "cvv": "123",
          "holder": "Peter Parker",
          "eci": "05",
          "aav": "avv123456abcd",
          "dsTransactionId": "33cdebf1-ff0c-4e33-a4b1-47e4c141fe58",
          "threeDSVersion": "V2",
          "verificationMethod": "ThreeDSecure"
      }
  }
  ```
</CodeGroup>

If you attempt authentication but the issuer doesn't support 3DS or its access control server doesn't respond, the liability shifts to the issuer, as long as the attempt includes a cryptogram (CAVV/AVV) from the card scheme's directory server. In this case, set the `verificationMethod` field to `ThreeDSecureAttempt`.