Overview

Monitor and track payment requests using the status endpoint and handle payment notifications.

Get Payment Request Status

Retrieve the current status of a payment request using its identifier.

API Endpoint

GET https://apay.caibo.digital/payment-requests/status/{id}

Authentication

HTTP Header: X-API-Key with your API key obtained from the dashboard
Content Type: application/json

Request Parameters

Parameter	Description	Required
`{id}`	Payment request identifier from payment creation response	YES

Response Fields

Field	Description	Type
`id`	Payment request identifier	string/integer
`recipientName`	Payment recipient name	string
`paymentRequestStatusId`	Payment request status: 1 – paid 2 – unpaid 3 – cancelled	integer
`transactionId`	Created transaction internal identifier	string/integer
`transactionNumber`	Created transaction public identifier	string
`transactionStatusId`	Created transaction status: 0 – waiting 1 – approved 2 – declined 3 – pending	integer
`link`	Payment request link to customer-facing web page	string
`unit`	Payment currency	string
`amount`	Payment amount	number
`referenceId`	Custom reference details	string
`notes`	Payment notes	string
`client`	Payment sender customer object	object
`notifyUrl`	Webhook URL for payment status notifications	string
`successUrl`	Redirect URL on successful payment	string
`failureUrl`	Redirect URL on failed payment	string
`lastLog`	Last payment attempt status and message	object

Last Log Object

Field	Description	Type
`transactionStatusId`	Last payment attempt status: 0 – waiting 1 – approved 2 – declined 3 – pending	integer
`message`	Last payment attempt message	string
`code`	Last payment attempt code	string

Example Request

curl -X GET \
  "https://apay.caibo.digital/payment-requests/status/16772761082427695" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json"

Payment Through SFTP

Process batch payments using SFTP file uploads for high-volume transactions.

SFTP Configuration

Credentials: Obtain SFTP address and credentials from the dashboard profile page
Multiple Providers: Different SFTP addresses may be available for different payment providers
File Format: Semicolon-delimited CSV without header row

CSV File Format

Each row represents a separate payment with the following fields in order:

Order	Field	Description	Required
1	Card holder name	Debit/credit card holder name	YES
2	Card number	Debit/credit card number	YES
3	Card expiration	Card expiration date (MM/YY format)	YES
4	Card CVV	Debit/credit card CVV code	YES
5	Email	Payer email address	YES
6	Phone	Payer phone number	YES
7	Address	Payer address	YES
8	City	Payer city name	YES
9	State	Payer state name or code (e.g., Florida or FL)	YES
10	Postal Code	Payer postal code	YES
11	Country	Payer country 2-letter ISO-3166-1 alpha-2 code (e.g., US)	YES
12	Amount	Payment amount (e.g., 10.50)	YES
13	Unit	Payment currency (e.g., USD, EUR, BTC, USDT)	YES
14	Reference ID	Merchant custom reference ID (free text)	NO

CSV Example

Test User;4111111111111111;10/25;123;testu@email.com;972540000000;10 Unknown Street;Far Town;NA;123456;IL;10.50;USD;RI12345

Important: Field order is critical and must be maintained exactly as specified.

Payment Notifications

Receive automated notifications about payment status changes via webhooks.

Notification Setup

Configuration: Set notify URL in dashboard profile page
Method: HTTP POST with application/x-www-form-urlencoded content type
Requirement: Notifications only sent if notify URL is configured

Notification Fields

Field	Description
`id`	Payment request identifier
`transactionId`	Payment request transaction identifier
`transactionStatusId`	Transaction status: 1 – approved, 2 – declined
`paymentRequestStatusId`	Payment status: 1 – paid, 2 – unpaid
`merchantId`	Merchant identifier (from control panel)
`unit`	Payment currency
`grossAmount`	Payment gross amount including fees
`fee`	Payment fee amount
`netAmount`	Net amount deposited to merchant wallet
`referenceId`	Custom reference details
`notes`	Payment notes
`clientId`	Payment sender customer identifier
`clientName`	Payment sender customer name
`clientEmail`	Payment sender customer email
`clientPhone`	Payment sender customer phone
`clientMemberId`	Payment sender customer member identifier
`message`	Payment failure reason message
`code`	Payment failure reason code

Example Notification

id=16772761082427695&transactionId=265111&transactionStatusId=1&paymentRequestStatusId=1&merchantId=16762420400394816&unit=USD&grossAmount=10&fee=0.5&netAmount=9.5&referenceId=12345&notes=Payment notes&clientId=16772748432912191&clientName=Client Name&clientEmail=client@email.com&clientPhone=1234567890&clientMemberId=12345&message=Stolen Card&code=008

Notification Verification

Verify notification authenticity using HMAC SHA512 signature.

Signature Verification

Header: Check X-Signature header in notification request
Algorithm: HMAC SHA512 hash in Base64 format
Key: Use your API key from the control panel

Verification Process

// Pseudo code for signature verification
const crypto = require('crypto');

function verifySignature(payload, signature, apiKey) {
  const hash = crypto
    .createHmac('sha512', apiKey)
    .update(payload)
    .digest('base64');
  
  return hash === signature;
}

// Usage
const isValid = verifySignature(requestBody, xSignatureHeader, yourApiKey);

Error Codes

Complete list of error codes and descriptions for troubleshooting.

Payment Processing Errors (001-020)

Code	Description
001	Bank system error. Try again later
002	Invalid or expired card
003	Card is blocked or restricted
004	3DS system decline
005	Insufficient funds
006	Security code (CVV/PIN) incorrect
007	Transaction blocked due to risk control
008	Unsupported card type
009	Invalid email address format
010	Invalid postal/zip code
011	Invalid credentials or encryption error
012	Transaction was cancelled
013	Authentication timed out
014	Declined: Origin domain is blocked
015	Declined: Callback URL is not allowed
016	Declined: Email is blocked due high CHB history
017	Declined: Card is blocked due high CHB history
018	Declined: Transaction exceeds max amount
019	Declined: Transaction less than min amount
020	Declined: Currency is not allowed

Limit and Validation Errors (021-048)

Code	Description
021	Declined: Number of transactions exceeded for today
022	Declined: Number of transactions exceeded this month
023	Declined: Total transaction amount exceeded for today
024	Declined: Total transaction amount exceeded this month
025	Invalid name
026	Invalid total amount
027	Invalid currency
028	Invalid reference
029	Invalid notify URL
030	Invalid success URL
031	Invalid failure URL
032	Invalid origin domain
033	Invalid phone number
034	Invalid address
035	Invalid city
036	Invalid state
037	Invalid country
038	Invalid UPI
039	Invalid capture delay hours
040	Invalid card number
041	Invalid card expiration
042	Invalid card CVV
043	Entity not found
044	Invalid customer
045	Invalid payment method
046	Invalid payment provider
047	Declined: Country is not allowed
048	Invalid token

System Errors (998-999)

Code	Description
998	System internal error. Contact system administrator
999	Transaction declined. Contact your card issuer

Best Practices

Status Checking

Polling: Check status periodically, not continuously
Rate Limiting: Respect API rate limits
Error Handling: Handle network timeouts and API errors gracefully

SFTP Batch Processing

File Validation: Validate CSV format before upload
Error Monitoring: Monitor notification responses for batch failures
Batch Size: Consider optimal batch sizes for your volume

Notification Handling

Signature Verification: Always verify notification signatures
Idempotency: Handle duplicate notifications gracefully
Response Time: Respond to notifications quickly (< 30 seconds)
Error Handling: Return appropriate HTTP status codes

Security

API Key Protection: Keep API keys secure and rotate regularly
HTTPS Only: Use HTTPS for all API communications
Signature Verification: Always verify webhook signatures
Error Logging: Log errors without exposing sensitive data

Path Parameters

integer

required

Customers

Payment Requests

Payment Status

Overview

Get Payment Request Status

API Endpoint

Authentication

Request Parameters

Response Fields

Last Log Object

Example Request

Payment Through SFTP

SFTP Configuration

CSV File Format

CSV Example

Payment Notifications

Notification Setup

Notification Fields

Example Notification

Notification Verification

Signature Verification

Verification Process

Error Codes

Payment Processing Errors (001-020)

Limit and Validation Errors (021-048)

System Errors (998-999)

Best Practices

Status Checking

SFTP Batch Processing

Notification Handling

Security

Path Parameters

Response

Customers

Payment Requests

​Overview

​Get Payment Request Status

​API Endpoint

​Authentication

​Request Parameters

​Response Fields

​Last Log Object

​Example Request

​Payment Through SFTP

​SFTP Configuration

​CSV File Format

​CSV Example

​Payment Notifications

​Notification Setup

​Notification Fields

​Example Notification

​Notification Verification

​Signature Verification

​Verification Process

​Error Codes

​Payment Processing Errors (001-020)

​Limit and Validation Errors (021-048)

​System Errors (998-999)

​Best Practices

​Status Checking

​SFTP Batch Processing

​Notification Handling

​Security

Path Parameters

Response

Overview

Get Payment Request Status

API Endpoint

Authentication

Request Parameters

Response Fields

Last Log Object

Example Request

Payment Through SFTP

SFTP Configuration

CSV File Format

CSV Example

Payment Notifications

Notification Setup

Notification Fields

Example Notification

Notification Verification

Signature Verification

Verification Process

Error Codes

Payment Processing Errors (001-020)

Limit and Validation Errors (021-048)

System Errors (998-999)

Best Practices

Status Checking

SFTP Batch Processing

Notification Handling

Security