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

# SDK setup

This guide explains how to integrate Paybyrd's 3D Secure (3DS) flow into your platform.

## Requirements

* API Key: Obtain your API key from the Developer Section in our dashboard.
* SDK: Add the Paybyrd SDK to your site. The steps below show you how.

## Step-by-step Guide

### 1. Initiating the Flow

Begin by creating a payment request using your API key:

```bash theme={null}
curl --request POST \
 --url https://gatewaysandbox.paybyrd.com/api/v2/payment \
 --header 'content-type: application/json' \
 --header 'x-api-key: {your_api_key}' \
 --data '{
 "type": "card",
 "isoAmount": 100,
 "currency": "EUR",
 "orderRef": "YOUR_REF_CODE_HERE",
 "redirectUrl": "https://your-shop-url?orderRef=YOUR_REF_CODE_HERE",
 "card": {
   "number": "5555341244441115",
   "expiration": "12/30",
   "cvv": "893",
   "holder": "Paybyrd"
 }
}'
```

<Warning>Execute this request from your backend. Sending card data from a client exposes credentials to end users.</Warning>

Minimal Request example:

```json theme={null}
{
 "type": "card",
 "isoAmount": 100,
 "currency": "EUR",
 "orderRef": "YOUR_REF_CODE_HERE",
 "redirectUrl": "https://your-shop-url?orderRef=YOUR_REF_CODE_HERE",
 "card": {
   "number": "5555341244441115",
   "expiration": "12/30",
   "cvv": "893",
   "holder": "Paybyrd"
 }
}
```

Response example:

```json theme={null}
{
 "type": "Card",
 "currency": "EUR",
 "orderRef": "YOUR_REF_CODE_HERE",
 "acquirer": "SIMULATED",
 "brand": "MASTER",
 "paymentMethod": "card",
 "redirectUrl": "https://your-shop-url?orderRef=YOUR_REF_CODE_HERE",
 "fingerprint": "d2456a93-4092-45ed-8f65-1446a255a8ed",
 "action": {
   "type": "redirect",
   "url": "https://link.paybyrd.com/3ds_yvLu4cxe8"
 },
 "code": "BYRD207",
 "description": "Pending redirect",
 "status": "Created",
 "requestId": "f2d40ac5-59ed-4528-a4c1-01641fd64bf7",
 "expiresAt": "2025-01-13T20:33:03.4365231Z",
 "acceptTokenization": false,
 "transactionMode": "None",
 "transactionId": "77f01ebc-2241-4c5f-8bfd-9cab6c81d74a",
 "amount": "1.00",
 "isoAmount": 100,
 "isPreAuth": false,
 "threeDSecure": {
   "id": "9e8cf073-c854-4534-97ae-1cea65695efb",
   "verificationMethod": "ThreeDSecure",
   "channel": "Browser",
   "status": "Created"
 }
}
```

<Tip>For full details on payment creation, see the [API reference](/api-reference/payments/create-payment).</Tip>

### 2. Handle the Payment Response

If the response contains code `BYRD207`, 3D Secure authentication is required before the payment can complete.

The response will include the following fields relevant to 3DS execution:

| Property                        | Description                                                                    |
| ------------------------------- | ------------------------------------------------------------------------------ |
| code                            | Indicates that 3DS authentication is required before the payment can complete. |
| action                          | Root node for any action available based on the request.                       |
| threeDSecure                    | Root node with information about 3DS.                                          |
| threeDSecure.id                 | A unique identifier for initiating the 3DS flow using the SDK.                 |
| threeDSecure.verificationMethod | Verification method used. Default is `ThreeDSecure`.                           |
| threeDSecure.channel            | Authentication channel. Default is `Browser`.                                  |
| threeDSecure.status             | Status of the 3DS process. Initially, this should be `Created`.                |
| requestId                       | The identification of the request in our service.                              |

### Using the SDK with threeDSecure.Id

1. Use the `threeDSecure.Id` and `requestId` value from the payment response to initiate the 3DS authentication within the Paybyrd SDK.
2. The SDK will handle the 3DS authentication process directly within your application.
3. Once the 3DS process is complete, retrieve the authentication result and proceed based on the returned status.

The SDK handles 3DS authentication inside your application without redirecting the customer.