### 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 "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." } ``` ```