> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caibo.digital/llms.txt
> Use this file to discover all available pages before exploring further.
# Payment Status
> Check payment request status and handle payment notifications
# 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
```bash theme={null}
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
```csv theme={null}
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¬es=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
1. **Header**: Check `X-Signature` header in notification request
2. **Algorithm**: HMAC SHA512 hash in Base64 format
3. **Key**: Use your API key from the control panel
### Verification Process
```javascript theme={null}
// 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
## OpenAPI
````yaml api GET /payment-requests/status/{id}
openapi: 3.0.4
info:
title: FinHub API
description: >-
FinHub API provides services for the Caibo platform to support client's
applications
version: v1
servers:
- url: https://apay.caibo.digital
description: Caibo APay server (Test and Production share base; method IDs differ)
security: []
paths:
/payment-requests/status/{id}:
get:
tags:
- PaymentRequests
parameters:
- name: id
in: path
required: true
schema:
type: integer
format: int64
responses:
'200':
description: OK
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
components:
schemas:
ProblemDetails:
type: object
properties:
type:
type: string
nullable: true
title:
type: string
nullable: true
status:
type: integer
format: int32
nullable: true
detail:
type: string
nullable: true
instance:
type: string
nullable: true
additionalProperties: {}
````