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

# Create Payment

The payments API offers you a set of different payment methods to facilitate the checkout experience. The API handles the underlying complexity, so you can integrate and start accepting payments quickly.

## Starting with the payments API

All the payment requests should be addressed to the endpoint `/api/v2/payment`. All payment methods follow the same request and response structure. The example below shows a simple card payment request:

```bash theme={null}
# Card Request
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 theme={null}
// Card Response
{
 "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://gateway.paybyrd.com/v1/ThreeDSecure/InitiatePayment?transactionId=0e443bff-9052-4eec-a5f1-9db474f2077a"
 },
 "card": {
   "number": "420000******0000",
   "expiration": "12/25",
   "cvv": "***",
   "holder": "Peter Parker"
 },
 "code": "BYRD207",
 "description": "Pending redirect"
}
```

The following example shows the same request using the iDeal payment method:

```bash theme={null}
# iDeal Request
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":"OnlineTransfer",
 "amount": "8.15",
 "currency": "EUR",
 "orderRef": "ABC12345",
 "brand": "ideal", 
 "bankIdentifierCode": "INGBNL2A",
 "redirectUrl": "https://your-shop-url?orderRef=ABC12345"
}'
```

```json theme={null}
// iDeal Response
{
 "transactionId": "6a842a44-790b-47c1-bfd1-0d9ffbe766d3",
 "amount": "8.15",
 "bankIdentifierCode": "INGBNL2A",
 "type": "OnlineTransfer",
 "currency": "EUR",
 "orderRef": "ABC12345",
 "brand": "ideal",
 "redirectUrl": "https://your-shop-url?orderRef=ABC12345",
 "action": {
   "type": "redirect",
   "url": "https://redirect.paybyrd.com/api/v1/redirect/6a842a44-790b-47c1-bfd1-0d9ffbe766d3"
 },
 "code": "BYRD207",
 "description": "Pending redirect"
}
```

Although these payment methods differ significantly, the request and response structure is consistent across all of them.

## Understanding the API

A successful integration starts with understanding the API's base structure. The table below describes the most important fields common to nearly all payment requests.

| Name        | Description                                                                                                                                                                                                                                                                                                                                                                   |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Type        | Indicates the type of the payment you want to create. For card payments, the type to be provided is "card". If you want to create a Multibanco reference for example, "onlineTransfer" must be chosen.                                                                                                                                                                        |
| Amount      | The amount to be charged or reserved from the shopper. The value must be provided as a string with the format "#.##".                                                                                                                                                                                                                                                         |
| Currency    | The currency which the shopper will be charged. The value must be in a valid ISO-4217 alpha code. E.g "EUR".                                                                                                                                                                                                                                                                  |
| OrderRef    | The merchant reference for the payment. Use it to identify the transaction in the Paybyrd dashboard or for reconciliation on your side.                                                                                                                                                                                                                                       |
| RedirectUrl | The URL where the shopper is redirected after the payment is completed. Many payment methods involve two steps — for example, card payment creation followed by 3D Secure authentication. After the shopper completes the second step, they are redirected to this URL. Paybyrd appends the `transactionId` as a query string, so you can query the final transaction status. |
| shopper     | Contains details about the buyer, including their full name, phone number, and billing address.                                                                                                                                                                                                                                                                               |

<Info>`RedirectUrl` can also be configured on your subscription. If set there, you do not need to include it in every request.</Info>