Payecards

https://docs.payecards.com
Admin
Payecards is a payment infrastructure platform providing merchant APIs for payment processing,...
Tokens:16,183
Snippets:105
Trust Score:5.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Create Transaction Response Example

Source: https://docs.payecards.com/docs/server2server/server_to_server

Response example for the Create Transaction endpoint. Shows a successful transaction with status 201 and a data object containing the transaction reference.

```json
{  

  "status": 201,  

  "data": {  

    "rrn": "TRX789012",  

    "status": "successful",  

    "amount": 1000.00,  

    "currency": "USD",  

    "reference": "REF456789"  

  },  

  "message": "Transaction successful"  

}  
```

--------------------------------

### List Transactions Response Example

Source: https://docs.payecards.com/docs/server2server/server_to_server

Response example for the List Transactions endpoint. Returns a paginated list of transactions with total count, current page, and limit.

```json
{  

  "status": 200,  

  "data": {  

    "transactions": [  

      {  

        "trans_id": "TRX789012",  

        "status": "successful",  

        "amount": 1000.00,  

        "currency": "USD",  

        "reference": "REF456789"  

      },  

      // ... more transactions ...  

    ],  

    "total": 50,  

    "page": 1,  

    "limit": 20  

  },  

  "message": "Transactions retrieved successfully"  

}  
```

--------------------------------

### Sample Request for CARD Payment Type

Source: https://docs.payecards.com/docs/crypto/crypto_buy

Example request body to initiate a crypto buy with a CARD payment method. The `payment_type` is set to "CARD" and, unlike the bank example, the `fiat_amount` is a number (50) rather than a string.

```json
{

  "payment_type": "CARD", // BANK or CARD  

  "fiat_currency": "USD",  

  "fiat_amount": 50,  

  "crypto_currency": "BTC",  

  "crypto_address": "765rtfghjkl98765rdfvbe345",  

  "crypto_currency_network": "BTC"  

}  
```

--------------------------------

### Sample Response of Uploading Payment Proof

Source: https://docs.payecards.com/docs/crypto/crypto_buy

Example response after successfully uploading a bank payment proof. The `file_url` points to the uploaded file on the CDN, and the transaction is marked as processing.

```json
{

  "success": true,  

  "data": {  

    "file_url": "https://cdn.payecards.com/payment-proof/tOpnGAQHATVIFJtbUTHcBsUL9jd7TF1H.png"  

  },  

  "message": "Payment proof uploaded successfully. Your transaction is processing."  

}  
```

--------------------------------

### Refund Transaction Response Example

Source: https://docs.payecards.com/docs/server2server/server_to_server

Response example for the Refund Transaction endpoint. Shows a successful refund with status 200 and operation_type REFUND.

```json
{  

  "status": 200,  

  "data": {  

    "result": "SUCCESSFUL",  

    "status": "SUCCESSFUL",  

    "rrn": "2w3eaeyw2dw4r9ras0aGw54t",  

    "currency": "GBP",  

    "amount": 2500,  

    "operation_type": "REFUND",  

    "trans_date": "2025-01-20T12:12:16.000000Z",  

    "trans_id": "U9kK3p6SqJKz5jvsINPCnuqM5u7RjQvk"  

  },  

  "message": "Transaction Refund Successful"  

}  
```

--------------------------------

### Webhook Response Failed Example

Source: https://docs.payecards.com/docs/webhook

Example of a failed webhook callback response. The status is 'FAILED' and includes a decline_reason indicating a timeout during 3D Secure authentication.

```json
{
  
    "status": "FAILED",  
    "rrn": "2w3eaeyw2dw4r9ras0aGw54t",  
    "currency": "GBP",  
    "amount": 2500,  
    "description": "payment for product",  
    "trans_date": "2025-01-20T12:12:16.000000Z",  
    "trans_id": "U9kK3p6SqJKz5jvsINPCnuqM5u7RjQvk",  
    "decline_reason": "3D Secure authentication was not completed. Timed out"  
}
```

--------------------------------

### Webhook Response Declined Example

Source: https://docs.payecards.com/docs/webhook

Example of a declined webhook callback response. The status is 'DECLINED' and includes a decline_reason field explaining why the transaction was declined.

```json
{
  
    "status": "DECLINED",  
    "rrn": "2w3eaeyw2dw4r9ras0aGw54t",  
    "currency": "GBP",  
    "amount": 2500,  
    "description": "payment for product",  
    "trans_date": "2025-01-20T12:12:16.000000Z",  
    "trans_id": "U9kK3p6SqJKz5jvsINPCnuqM5u7RjQvk",  
    "decline_reason": "The card does not support 3D Secure authentication. Please use a different card or contact your bank"  
}
```

--------------------------------

### Sample Request for Bank Payment Type

Source: https://docs.payecards.com/docs/crypto/crypto_buy

Example request body to initiate a crypto buy with a BANK payment. The `payment_type` is set to "BANK" and the system will generate a unique `ref_id` for this request.

```json
{

  "payment_type": "BANK", // BANK or CARD  

  "fiat_currency": "USD",  

  "fiat_amount": "50",  

  "crypto_currency": "BTC",  

  "crypto_address": "765rtfghjkl98765rdfvbe345",  

  "crypto_currency_network": "BTC"  

}  
```

--------------------------------

### Webhook Response Success Example

Source: https://docs.payecards.com/docs/webhook

Example of a successful webhook callback response. The status is 'SUCCESSFUL' and includes transaction details such as rrn, currency, amount, description, trans_date, and trans_id.

```json
{
  
    "status": "SUCCESSFUL",  
    "rrn": "2w3eaeyw2dw4r9ras0aGw54t",  
    "currency": "GBP",  
    "amount": 2500,  
    "description": "payment for product",  
    "trans_date": "2025-01-20T12:12:16.000000Z",  
    "trans_id": "U9kK3p6SqJKz5jvsINPCnuqM5u7RjQvk"  
}
```

--------------------------------

### Verify Transaction Response Example

Source: https://docs.payecards.com/docs/server2server/server_to_server

Response example for the Verify Transaction endpoint. Returns status 200 with transaction details including rrn, status, amount, currency, and reference.

```json
{  

  "status": 200,  

  "data": {  

    "rrn": "TRX789012",  

    "status": "successful",  

    "amount": 1000.00,  

    "currency": "USD",  

    "reference": "TXN123456"  

  },  

  "message": "Transaction verified"  

}  
```

--------------------------------

### Sample Request to Upload Payment Proof

Source: https://docs.payecards.com/docs/crypto/crypto_buy

Example to upload the bank payment proof after transferring the `fiat_amount`. It requires the `ref_id` returned from a BANK-type buy request and a `payment_proof` file of type jpg, pdf, jpeg, or png.

```json
{

  "ref_id": "b44f8101-817a-4521-af5e-d95fb162177c",  

  "payment_proof": "File - jpg, pdf, jpeg, or png"  

}  
```

--------------------------------

### Sample Request for POST /api/v2/gateway/transaction

Source: https://docs.payecards.com/docs/collection/checkout

Example JSON request body for initiating a checkout transaction. Includes payment methods, order details, customer information, and optional fields like mid, recurring_type, and billing_descriptor.

```json
{
  "payment_methods": ["credit_card", "bank_transfer"],
  "order": {
    "amount": 100.00,
    "description": "Purchase of Product XYZ",
    "currency": "USD",
    "fee_bearer": "MERCHANT"
  },
  "customer": {
    "email": "john.doe@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "ip": "192.168.1.1",
    "phone": "1234567890"
  },
  "mid": "MERCH001",
  "recurring_type": "one_time",
  "billing_descriptor": "XYZ Store"
}
```

--------------------------------

### Sample Request for Card Payout

Source: https://docs.payecards.com/docs/disbursement/gateway_payout

Example JSON request body for initiating a card payout. Includes currency, amount, client phone number, date of birth, and card details. The system generates a unique transaction reference for each request.

```json
{

    "currency": "USD",

    "amount": 100.0,

    "client_phone_number": "+2348190987610",

    "date_of_birth": "1999-04-10", //y-m-d

    "card": {

        "card_number": "4111111111111111",

        "card_holder_name": "John Doe",

        "cvv": 345,

        "exp_year": "26",

        "exp_month": "12"

    }

}
```

--------------------------------

### GET /api/v3/crypto/buy/list?limit=20

Source: https://docs.payecards.com/docs/crypto/crypto_buy

Lists crypto buy transactions. The endpoint is used to retrieve a list of crypto buy transactions.

```APIDOC
## GET /api/v3/crypto/buy/list?limit=20

### Description
Lists crypto buy transactions. The endpoint is used to retrieve a list of crypto buy transactions.

### Method
GET

### Endpoint
/api/v3/crypto/buy/list?limit=20

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of transactions to return (default 20)

### Response
#### Success Response (200)
- **success** (boolean) - Indicates success
- **data** (array) - List of transactions
- **message** (string) - Response message

#### Error Response
```
{
  "success": false,
  "message": "Unknown error. Try again later or contact us"
}
```
```

--------------------------------

### GET /api/v3/crypto/sell/list?limit=20

Source: https://docs.payecards.com/docs/crypto/crypto_sell

Lists crypto sell transactions. The endpoint accepts a limit query parameter.

```APIDOC
## GET /api/v3/crypto/sell/list?limit=20

### Description
Lists crypto sell transactions. The endpoint accepts a limit query parameter.

### Method
GET

### Endpoint
/api/v3/crypto/sell/list?limit=20

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of transactions to return (default 20)

### Response
#### Success Response (200)
- **success** (boolean) - Indicates success
- **data** (array) - List of transactions
- **message** (string) - Success message

#### Error Response
- **success** (boolean) - false
- **message** (string) - Error message

#### Error Response Example
{
  "success": false,
  "message": "Unknown error. Try again later or contact us"
}
```

--------------------------------

### List Transactions Request Example

Source: https://docs.payecards.com/docs/server2server/server_to_server

Request body for the List Transactions endpoint. Both fields are optional; limit defaults to 20 and page defaults to 1.

```json
{  

  "limit": 20,  

  "page": 1  

}  
```

--------------------------------

### Successful Response for CARD Payment Type

Source: https://docs.payecards.com/docs/crypto/crypto_buy

Example response confirming a CARD payment request. It includes a `checkout_url` that you must redirect the user to in order to complete the card payment. The `fee_amount` is 5.00 and the `total_amount` is 55.

```json
{

  "success": true,  

  "data": {  

    "payment_type": "CARD",  

    "fiat_currency": "USD",  

    "fiat_amount": 50,  

    "fee_amount": 5.00,  

    "total_amount": 55,  

    "crypto_currency": "BTC",  

    "crypto_amount": "0.00045570",  

    "ref_id": "2a2c104b-442a-46c9-9e1b-6b74d617bda6",  

    "checkout_url": "https://payecards.com/crypto-buy/2a2c104b-442a-46c9-9e1b-6b74d617bda6"  

  },  

  "message": "Crypto buy request initiated"  

}  
```

--------------------------------

### Verify Transaction Request Example

Source: https://docs.payecards.com/docs/server2server/server_to_server

Request body for the Verify Transaction endpoint. The reference field is required and should be the transaction rrn or trans_id.

```json
{  

  "reference": "TXN123456"  

}  
```

--------------------------------

### Successful Response for BANK Payment Type

Source: https://docs.payecards.com/docs/crypto/crypto_buy

Example response after a BANK payment request. It includes the bank details (`bic_swift`, `iban`, `bank_name`) to which the `fiat_amount` must be transferred, and the generated `ref_id`. The `fee_amount` is "5.00" and the `total_amount` is 55.

```json
{

  "success": true,  

  "data": {  

    "bic_swift": "RolexBank",  

    "iban": "3245675432456",  

    "beneficairy_name": "Kenan Holt",  

    "bank_name": "Rolex Bank",  

    "fiat_currency": "USD",  

    "fiat_amount": 50,  

    "fee_amount": "5.00",  

    "total_amount": 55,  

    "crypto_currency": "BTC",  

    "crypto_amount": "0.00045688",  

    "ref_id": "de511138-14f2-402d-8c6e-76ad001388d8"  

  },  

  "message": "Make bank payment to the bank details"  

}  
```

--------------------------------

### General Error Response

Source: https://docs.payecards.com/docs/crypto/crypto_buy

Example of a generic error response for the Crypto Buy API, indicating a failure with the message "Unknown error. Try again later or contact us".

```json
{

  "success": false,  

  "message": "Unknown error. Try again later or contact us"  

}  
```

--------------------------------

### Refund Transaction Request Example

Source: https://docs.payecards.com/docs/server2server/server_to_server

Request body for the Refund Transaction endpoint. The trans_id field is required and should be the transaction id to refund.

```json
{  

  "trans_id": "TXN123456"  

}  
```

--------------------------------

### Create Transaction Request Example

Source: https://docs.payecards.com/docs/server2server/server_to_server

Request body for the Create Transaction endpoint. All fields except billing.address2 and return_url_3d are required; card number must be 13-19 digits, expiry month/year 2 digits, CVV 3 digits, and phone in international format.

```json
{  

  "rrn": "TXN123456",  

  "order": {  

    "amount": 1000.00,  

    "description": "Product purchase",  

    "currency": "USD",  

  },  

  "customer": {  

    "email": "customer@example.com",  

    "firstname": "John",  

    "lastname": "Doe",  

    "ip": "192.168.1.1",  

    "phone": "+901234567890"  

  },  

  "card": {  

    "number": "4123000000000000",  

    "exp_month": "01",  

    "exp_year": "35",  

    "cvv": "100",  

    "card_holder_name": "Holt Norman"  

  },  

  "billing": {  

    "address1": "123 Main St",  

    "address2": "Apt 4B",  

    "city": "Anytown",  

    "state": "CA",  

    "country": "US",  

    "zip": "12345"  

  },  

  "return_url_3d": "http://merchant-website.com/return-3d-url"  

}  
```

--------------------------------

### Successful Response for Card Payout

Source: https://docs.payecards.com/docs/disbursement/gateway_payout

Example JSON response for a successful card payout request. Contains status, message, and data including amount, currency, payment methods, customer details, and checkout URL.

```json
{

  "status": "success",

  "message": "Card Payout request has been completed successfully",

  "data": {

    "amount": 100.00,

    "currency": "USD",

    "payment_methods": ["credit_card", "bank_transfer"],

    "customer": {

      "email": "john.doe@example.com",

      "firstname": "John",

      "lastname": "Doe",

      "ip": "192.168.1.1",

      "phone": "1234567890"

    },

    "checkout_url": "https://example.com/checkout/encrypted-reference"

  }

}
```

--------------------------------

### Successful Response for POST /api/v2/gateway/transaction

Source: https://docs.payecards.com/docs/collection/checkout

Example JSON response for a successful checkout transaction. Contains status, message, and data including amount, currency, payment methods, customer info, and a checkout_url with an encrypted reference.

```json
{
  "status": "success",
  "message": "Operation successful",
  "data": {
    "amount": 100.00,
    "currency": "USD",
    "payment_methods": ["credit_card", "bank_transfer"],
    "customer": {
      "email": "john.doe@example.com",
      "firstname": "John",
      "lastname": "Doe",
      "ip": "192.168.1.1",
      "phone": "1234567890"
    },
    "checkout_url": "https://example.com/checkout/encrypted-reference"
  }
}
```

--------------------------------

### Error Response for POST /api/v2/gateway/transaction

Source: https://docs.payecards.com/docs/collection/checkout

Example JSON response for a failed checkout transaction. Contains status 'error', a generic error message, and null data.

```json
{
  "status": "error",
  "message": "Sorry, we were unable to process your transaction. Please contact us.",
  "data": null
}
```

--------------------------------

### Error Response for Card Payout

Source: https://docs.payecards.com/docs/disbursement/gateway_payout

Example JSON response for a failed card payout request. Contains success flag and error message indicating the transaction was declined due to security rules.

```json
{

    "success": false,

    "message": "Sorry, we were unable to process your transaction. The transaction was declined due to security rules."

}
```

--------------------------------

### PHP cURL transaction creation

Source: https://docs.payecards.com/docs/server2server/server_to_server

PHP example using cURL to create a transaction via the server-to-server API. Replace the base URL with the actual one from the testing section and the merchant key with your own. The script sends a JSON payload with order, customer, card, and billing details, then checks for a 201 status to output the result or an error message.

```php
<?php

$data = [
  "rrn" => "TXN" . time(),
  "order" => [
    "amount" => 10.00,
    "description" => "Product purchase",
    "currency" => "USD",
    "fee_bearer" => "CUSTOMER"
  ],
  "customer" => [
    "email" => "customer@example.com",
    "firstname" => "John",
    "lastname" => "Doe",
    "ip" => $_SERVER['REMOTE_ADDR'],
    "phone" => "+901234567890"
  ],
  "card" => [
    "number" => "4123000000000000",
    "exp_month" => "12",
    "exp_year" => "25",
    "cvv" => "100",
    "card_holder_name": "Holt Norman"
  ],
  "billing" => [
    "address1" => "123 Main St",
    "address2" => "Apt 4B",
    "city" => "Anytown",
    "state" => "CA",
    "country" => "US",
    "zip" => "12345"
  ],
  "return_url_3d" => "http://merchant-website.com/return-3d-url"
];

$ch = curl_init('https://api.example.com/gateway/transaction/s2s/create');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Content-Type: application/json',
  'X-Merchant-Key: your_merchant_key_here'
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

if ($result['status'] === 201) {
  echo "Transaction result - " . json_encode($result);
} else {
  echo "Error: " . $result['message'];
}
```

--------------------------------

### POST /api/v3/crypto/buy/handle

Source: https://docs.payecards.com/docs/crypto/crypto_buy

Initiates a crypto buy transaction. The system will generate a unique reference id (ref_id) for each request.

```APIDOC
## POST /api/v3/crypto/buy/handle

### Description
Initiates a crypto buy transaction. The system will generate a unique reference id (ref_id) for each request.

### Method
POST

### Endpoint
/api/v3/crypto/buy/handle

### Headers
- **apiKey** (string) - Required - Your unique merchant key for authentication

### Parameters
#### Request Body
- **payment_type** (String) - Required - Payment types are CARD and BANK
- **fiat_currency** (String) - Required - USD only
- **crypto_currency** (String) - Required - Allowed Cryptocurrencies BTC, USDT
- **crypto_currency_network** (string) - Required - Allowed networks BTC, TRC20
- **fiat_amount** (Numeric) - Required - Must be greater than one
- **crypto_address** (String) - Required - A valid crypto address

### Request Example
```
{
  "payment_type": "BANK", // BANK or CARD
  "fiat_currency": "USD",
  "fiat_amount": "50",
  "crypto_currency": "BTC",
  "crypto_address": "765rtfghjkl98765rdfvbe345",
  "crypto_currency_network": "BTC"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates success
- **data** (object) - Contains transaction details
- **message** (string) - Response message

#### Response Example (BANK)
```
{
  "success": true,
  "data": {
    "bic_swift": "RolexBank",
    "iban": "3245675432456",
    "beneficairy_name": "Kenan Holt",
    "bank_name": "Rolex Bank",
    "fiat_currency": "USD",
    "fiat_amount": 50,
    "fee_amount": "5.00",
    "total_amount": 55,
    "crypto_currency": "BTC",
    "crypto_amount": "0.00045688",
    "ref_id": "de511138-14f2-402d-8c6e-76ad001388d8"
  },
  "message": "Make bank payment to the bank details"
}
```

#### Response Example (CARD)
```
{
  "success": true,
  "data": {
    "payment_type": "CARD",
    "fiat_currency": "USD",
    "fiat_amount": 50,
    "fee_amount": 5.00,
    "total_amount": 55,
    "crypto_currency": "BTC",
    "crypto_amount": "0.00045570",
    "ref_id": "2a2c104b-442a-46c9-9e1b-6b74d617bda6",
    "checkout_url": "https://payecards.com/crypto-buy/2a2c104b-442a-46c9-9e1b-6b74d617bda6"
  },
  "message": "Crypto buy request initiated"
}
```
```

--------------------------------

### Sample Request for CARD Payment Type

Source: https://docs.payecards.com/docs/crypto/crypto_sell

JSON request body for initiating a crypto sell transaction using the CARD payment type.

```json
{

  "recieve_type": "CARD", // BANK or CARD

  "fiat_currency": "USD",

  "fiat_amount": 50,

  

  "crypto_currency": "BTC",

  "crypto_amount": 0.0034,

  "crypto_address": "765rtfghjkl98765rdfvbe345",

  "crypto_currency_network": "BTC",

  

  "card_number": "5123000000000000",

  "card_holder_name": "Olman Tyson"

}
```

--------------------------------

### Sample Request for Bank Payment Type

Source: https://docs.payecards.com/docs/crypto/crypto_sell

JSON request body for initiating a crypto sell transaction using the BANK payment type.

```json
{

  "recieve_type": "BANK", // BANK or CARD

  "fiat_currency": "USD",

  "fiat_amount": "50",

  

  "crypto_currency": "BTC",

  "crypto_amount": 0.0034,

  "crypto_address": "765rtfghjkl98765rdfvbe345",

  "crypto_currency_network": "BTC",

  

  "bank_account_no": "9876546789",

  "bank_swift_code": "57RTF",

  "bank_name": "Citi Bank",

  "bank_account_name": "Lighton Bills",

  "bank_address": "No 456 Roland Road NY",

  "account_holder_address": "Suite 340 Elim Plaza London",

}
```

--------------------------------

### POST /api/v3/crypto/sell/handle

Source: https://docs.payecards.com/docs/crypto/crypto_sell

Creates a crypto sell transaction. The transaction is created with a status of PENDING initially and an admin will process it.

```APIDOC
## POST /api/v3/crypto/sell/handle

### Description
Creates a crypto sell transaction. The transaction is created with a status of PENDING initially and an admin will process it.

### Method
POST

### Endpoint
/api/v3/crypto/sell/handle

### Headers
- **apiKey** (string) - Required - Your unique merchant key for authentication

### Parameters
#### Request Body
- **payment_type** (String) - Required - Payment types are CARD and BANK
- **fiat_currency** (String) - Required - USD only
- **crypto_currency** (String) - Required - Allowed Cryptocurrencies BTC, USDT
- **crypto_currency_network** (string) - Required - Allowed networks BTC, TRC20
- **fiat_amount** (Numeric) - Required - Must be greater than one
- **crypto_address** (String) - Required - A valid crypto address

### Request Example
{
  "recieve_type": "BANK", // BANK or CARD
  "fiat_currency": "USD",
  "fiat_amount": "50",
  "crypto_currency": "BTC",
  "crypto_amount": 0.0034,
  "crypto_address": "765rtfghjkl98765rdfvbe345",
  "crypto_currency_network": "BTC",
  "bank_account_no": "9876546789",
  "bank_swift_code": "57RTF",
  "bank_name": "Citi Bank",
  "bank_account_name": "Lighton Bills",
  "bank_address": "No 456 Roland Road NY",
  "account_holder_address": "Suite 340 Elim Plaza London"
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates success
- **data** (object) - Contains transaction details
  - **recieve_type** (string) - Payment type
  - **fiat_currency** (string) - Fiat currency
  - **crypto_currency** (string) - Crypto currency
  - **fiat_amount** (number) - Fiat amount
  - **crypto_amount** (number) - Crypto amount
  - **total_amount** (number) - Total amount including fees
  - **crypto_currency_network** (string) - Network
  - **fee_amount** (number) - Fee amount
  - **ref_id** (string) - Unique reference id
  - **created_at** (string) - Creation timestamp
  - **status** (string) - Status (PENDING)
- **message** (string) - Success message

#### Response Example
{
  "success": true,
  "data": {
    "recieve_type": "CARD",
    "fiat_currency": "USD",
    "crypto_currency": "BTC",
    "fiat_amount": 50,
    "crypto_amount": 0.0034,
    "total_amount": 53.5,
    "crypto_currency_network": "BTC",
    "fee_amount": 3.50,
    "ref_id": "9eef4379-a7a6-4cf9-919f-2259ce00c7ec",
    "created_at": "2025-06-10T13:49:48.000000Z",
    "status": "PENDING"
  },
  "message": "Crypto sell request successfull"
}

#### Error Response
- **success** (boolean) - false
- **message** (string) - Error message

#### Error Response Example
{
  "success": false,
  "message": "Unknown error. Try again later or contact us"
}
```

--------------------------------

### POST /api/v3/crypto/buy/upload-proof

Source: https://docs.payecards.com/docs/crypto/crypto_buy

Uploads the payment proof for a bank payment type crypto buy transaction. The endpoint to upload payment proof can be found below.

```APIDOC
## POST /api/v3/crypto/buy/upload-proof

### Description
Uploads the payment proof for a bank payment type crypto buy transaction. The endpoint to upload payment proof can be found below.

### Method
POST

### Endpoint
/api/v3/crypto/buy/upload-proof

### Headers
- **apiKey** (string) - Required - Your unique merchant key for authentication

### Parameters
#### Request Body
- **ref_id** (String) - Required - Value returned from Crypto buy request of payment typr BANK
- **payment_proof** (File) - Required - Has to be jpg, pdf, jpeg, or png

### Request Example
```
{
  "ref_id": "b44f8101-817a-4521-af5e-d95fb162177c",
  "payment_proof": "File - jpg, pdf, jpeg, or png"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates success
- **data** (object) - Contains file URL
- **message** (string) - Response message

#### Response Example
```
{
  "success": true,
  "data": {
    "file_url": "https://cdn.payecards.com/payment-proof/tOpnGAQHATVIFJtbUTHcBsUL9jd7TF1H.png"
  },
  "message": "Payment proof uploaded successfully. Your transaction is processing."
}
```
```

--------------------------------

### Successful Response

Source: https://docs.payecards.com/docs/crypto/crypto_sell

The JSON response returned upon a successful crypto sell request, including the generated ref_id.

```json
{

  "success": true,

  "data": {

    "recieve_type": "CARD",

    "fiat_currency": "USD",

    "crypto_currency": "BTC",

    "fiat_amount": 50,

    "crypto_amount": 0.0034,

    "total_amount": 53.5,

    "crypto_currency_network": "BTC",

    "fee_amount": 3.50,

    "ref_id": "9eef4379-a7a6-4cf9-919f-2259ce00c7ec",

    "created_at": "2025-06-10T13:49:48.000000Z",

    "status": "PENDING"

  },

  "message": "Crypto sell request successfull"

}
```

--------------------------------

### POST /gateway/transaction/s2s/create

Source: https://docs.payecards.com/docs/server2server/server_to_server

Creates a new transaction with the provided order, customer, card, and billing details. This endpoint initiates a server-to-server transaction request.

```APIDOC
## POST /gateway/transaction/s2s/create

### Description
Creates a new transaction with the provided order, customer, card, and billing details. This endpoint initiates a server-to-server transaction request.

### Method
POST

### Endpoint
/gateway/transaction/s2s/create

### Parameters
#### Request Body
- **rrn** (string) - Required - Unique reference for the transaction (Alphanumeric only)
- **order.amount** (number) - Required - Transaction amount
- **order.description** (string) - Required - Description of the transaction
- **order.currency** (string) - Required - Currency code (must exist in the system)
- **customer.email** (string) - Required - Customer's email address
- **customer.firstname** (string) - Required - Customer's first name
- **customer.lastname** (string) - Required - Customer's last name
- **customer.ip** (string) - Required - Customer's IP address
- **customer.phone** (string) - Required - Customer's phone number (Must be in International format)
- **card.number** (string) - Required - Card number (13-19 digits)
- **card.exp_month** (string) - Required - Card expiry month (2 digits)
- **card.exp_year** (string) - Required - Card expiry year (2 digits)
- **card.cvv** (string) - Required - Card CVV (3 digits)
- **card.card_holder_name** (string) - Required - Card Holder Name (String Max 255 Characters)
- **billing.address1** (string) - Required - Billing address line 1
- **billing.address2** (string) - Optional - Billing address line 2
- **billing.city** (string) - Required - Billing city
- **billing.state** (string) - Required - Billing state
- **billing.country** (string) - Required - Billing country (2-letter code)
- **billing.zip** (string) - Required - Billing zip/postal code
- **return_url_3d** (string) - Optional - Where to return users to after 3d checkout

### Request Example
{
  "rrn": "TXN123456",
  "order": {
    "amount": 1000.00,
    "description": "Product purchase",
    "currency": "USD"
  },
  "customer": {
    "email": "customer@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "ip": "192.168.1.1",
    "phone": "+901234567890"
  },
  "card": {
    "number": "4123000000000000",
    "exp_month": "01",
    "exp_year": "35",
    "cvv": "100",
    "card_holder_name": "Holt Norman"
  },
  "billing": {
    "address1": "123 Main St",
    "address2": "Apt 4B",
    "city": "Anytown",
    "state": "CA",
    "country": "US",
    "zip": "12345"
  },
  "return_url_3d": "http://merchant-website.com/return-3d-url"
}

### Response
#### Success Response (201)
- **status** (number) - HTTP status code
- **data.rrn** (string) - Transaction reference number
- **data.status** (string) - Transaction status
- **data.amount** (number) - Transaction amount
- **data.currency** (string) - Currency code
- **data.reference** (string) - Reference identifier
- **message** (string) - Response message

#### Response Example
{
  "status": 201,
  "data": {
    "rrn": "TRX789012",
    "status": "successful",
    "amount": 1000.00,
    "currency": "USD",
    "reference": "REF456789"
  },
  "message": "Transaction successful"
}
```

--------------------------------

### POST /gateway/transaction/s2s/create

Source: https://docs.payecards.com/docs/server2server/server_to_server

Creates a new transaction using the server-to-server integration. The request includes order, customer, card, and billing details, and optionally a 3D return URL.

```APIDOC
## [POST] /gateway/transaction/s2s/create

### Description
Creates a new transaction using the server-to-server integration. The request includes order, customer, card, and billing details, and optionally a 3D return URL.

### Method
POST

### Endpoint
/gateway/transaction/s2s/create

### Parameters
#### Request Body
- **rrn** (string) - Required - Unique transaction reference number.
- **order** (object) - Required - Contains amount, description, currency, and fee_bearer.
  - **amount** (number) - Required - Transaction amount.
  - **description** (string) - Required - Description of the purchase.
  - **currency** (string) - Required - Currency code (e.g., USD).
  - **fee_bearer** (string) - Required - Who bears the fee (e.g., CUSTOMER).
- **customer** (object) - Required - Contains email, firstname, lastname, ip, and phone.
  - **email** (string) - Required - Customer email.
  - **firstname** (string) - Required - Customer first name.
  - **lastname** (string) - Required - Customer last name.
  - **ip** (string) - Required - Customer IP address.
  - **phone** (string) - Required - Customer phone number.
- **card** (object) - Required - Contains number, exp_month, exp_year, cvv, and card_holder_name.
  - **number** (string) - Required - Card number.
  - **exp_month** (string) - Required - Card expiration month.
  - **exp_year** (string) - Required - Card expiration year.
  - **cvv** (string) - Required - Card CVV.
  - **card_holder_name** (string) - Required - Name on card.
- **billing** (object) - Required - Contains address1, address2, city, state, country, and zip.
  - **address1** (string) - Required - Billing address line 1.
  - **address2** (string) - Optional - Billing address line 2.
  - **city** (string) - Required - Billing city.
  - **state** (string) - Required - Billing state.
  - **country** (string) - Required - Billing country code.
  - **zip** (string) - Required - Billing zip code.
- **return_url_3d** (string) - Optional - URL for 3D Secure return.

### Request Example
{
  "rrn": "TXN" . time(),
  "order": {
    "amount": 10.00,
    "description": "Product purchase",
    "currency": "USD",
    "fee_bearer": "CUSTOMER"
  },
  "customer": {
    "email": "customer@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "ip": "127.0.0.1",
    "phone": "+901234567890"
  },
  "card": {
    "number": "4123000000000000",
    "exp_month": "12",
    "exp_year": "25",
    "cvv": "100",
    "card_holder_name": "Holt Norman"
  },
  "billing": {
    "address1": "123 Main St",
    "address2": "Apt 4B",
    "city": "Anytown",
    "state": "CA",
    "country": "US",
    "zip": "12345"
  },
  "return_url_3d": "http://merchant-website.com/return-3d-url"
}

### Response
#### Success Response (201)
- **status** (number) - HTTP status code (201 for success).
- **data** (object) - Transaction result data.
- **message** (string) - Success message.

#### Response Example
{
  "status": 201,
  "data": {},
  "message": "Transaction created successfully"
}

#### Error Response
- **status** (number) - HTTP status code (400, 401, 404, 500).
- **data** (null) - Always null on error.
- **message** (string) - Error description.

#### Error Response Example
{
  "status": 400,
  "data": null,
  "message": "Error description"
}

### Error Handling
Common error status codes:
- 400: Bad Request (invalid parameters)
- 401: Unauthorized (invalid merchant key)
- 404: Not Found (transaction not found)
- 500: Internal Server Error

### Authentication
Requires an `X-Merchant-Key` header with a valid merchant key.

### Headers
- **Content-Type** (string) - Required - Must be `application/json`.
- **X-Merchant-Key** (string) - Required - Merchant key for authentication.

### Notes
- Replace the base URL with the actual base URL from the testing section.
- Replace `your_merchant_key_here` with your actual merchant key.
```

--------------------------------

### API Authentication Header

Source: https://docs.payecards.com/docs/authorization/authentication_and_authorization

Include the X-Merchant-Key header in your API requests to authenticate.

```json
{

    "X-Merchant-Key": "your_merchant_key_here'

  }
```

--------------------------------

### POST /api/v2/gateway/card-payout

Source: https://docs.payecards.com/docs/disbursement/gateway_payout

Initiates a card payout (withdrawal) for a client using the provided card details and payout amount.

```APIDOC
## POST /api/v2/gateway/card-payout

### Description
Initiates a card payout (withdrawal) request for a client. The request must include the client's phone number, birth date, payout amount, currency, and card details.

### Method
POST

### Endpoint
/api/v2/gateway/card-payout

### Headers
| Header | Value | Description |
| --- | --- | --- |
| `x-merchant-key` | string | Your unique merchant key for authentication |

### Parameters
#### Request Body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `currency` | string | Yes | Currency for payout (must be a supported currency) |
| `amount` | numeric | Yes | Payout amount (must be greater than 0) |
| `client_phone_number` | string | Yes | Client's phone number |
| `date_of_birth` | string | Yes | Client's birth date (format: Y-m-d) |
| `card.number` | string | Yes | Card number (13-19 digits) |
| `card.card_holder_name` | string | Yes | Card holder name (string, max 255 characters) |
| `card.cvv` | string | Yes | Card CVV (3 digits) |
| `card.exp_month` | string | Yes | Card expiry month (2 digits) |
| `card.exp_year` | string | Yes | Card expiry year (4 digits) |

### Request Example
```json
{
  "currency": "USD",
  "amount": 100.0,
  "client_phone_number": "+2348190987610",
  "date_of_birth": "1999-04-10", //y-m-d
  "card": {
    "card_number": "4111111111111111",
    "card_holder_name": "John Doe",
    "cvv": 345,
    "exp_year": "26",
    "exp_month": "12"
  }
}
```

### Response
#### Success Response (200)
| Field | Type | Description |
| --- | --- | --- |
| `status` | string | Indicates success |
| `message` | string | Success message |
| `data.amount` | number | The payout amount |
| `data.currency` | string | The currency |
| `data.payment_methods` | array | Payment methods available |
| `data.customer.email` | string | Customer email |
| `data.customer.firstname` | string | Customer first name |
| `data.customer.lastname` | string | Customer last name |
| `data.customer.ip` | string | IP address |
| `data.customer.phone` | string | Customer phone |
| `data.checkout_url` | string | URL with encrypted reference |

#### Response Example
```json
{
  "status": "success",
  "message": "Card Payout request has been completed successfully",
  "data": {
    "amount": 100.00,
    "currency": "USD",
    "payment_methods": ["credit_card", "bank_transfer"],
    "customer": {
      "email": "john.doe@example.com",
      "firstname": "John",
      "lastname": "Doe",
      "ip": "192.168.1.1",
      "phone": "1234567890"
    },
    "checkout_url": "https://example.com/checkout/encrypted-reference"
  }
}
```

#### Error Response
Error response structure:
```json
{
  "success": false,
  "message": "Sorry, we were unable to process your transaction. The transaction was declined due to security rules."
}
```
```
Tokens:
Raw