SUNRATE International Payments & Commercial Cards

https://docs.sunrate.com/
Admin
SUNRATE offers global payment and treasury management solutions, including international payments...
Tokens:24,842
Snippets:52
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Trade - Get Quote

Source: https://docs.sunrate.com/index

Request a quote for a foreign exchange trade.

```APIDOC
## POST /openapi/v3/fxquote/getSingleQuote

### Description
Requests a real-time quote for a foreign exchange trade.

### Method
POST

### Endpoint
/openapi/v3/fxquote/getSingleQuote

### Parameters
#### Request Body
- **appId** (String) - Required - Unique identifier of a client assigned by Sunrate
- **msgId** (String) - Required - The request message ID
- **bizId** (String) - Optional - Business ID
- **ip** (String) - Required - User’s browser IP address.
- **version** (String) - Required - Endpoint version. Fixed value “3.0”
- **callbackUrl** (String) - Optional - Callback URL for status updates
- **timestamp** (String) - Required - Timestamp of request, formatted as "yyyy-MM-ddTHH:mm:ss.SSS"
- **key** (String) - Required - Private key value of 16-digit AES after encryption.
- **sign** (String) - Required - Signature value
- **requestBody** (String) - Required - Encrypted request body containing trade details (e.g., currency pair, amount). Format in JSON before encryption.
```

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

### Onboarding - Submit KYC

Source: https://docs.sunrate.com/index

Submit KYC information to register a client with Sunrate.

```APIDOC
## POST /openapi/v3/register/create/

### Description
Submits KYC information for client registration.

### Method
POST

### Endpoint
/openapi/v3/register/create/

### Parameters
#### Request Body
- **appId** (String) - Required - Unique identifier of a client assigned by Sunrate
- **msgId** (String) - Required - The request message ID
- **bizId** (String) - Optional - Business ID
- **ip** (String) - Required - User’s browser IP address.
- **version** (String) - Required - Endpoint version. Fixed value “3.0”
- **callbackUrl** (String) - Optional - Callback URL for status updates
- **timestamp** (String) - Required - Timestamp of request, formatted as "yyyy-MM-ddTHH:mm:ss.SSS"
- **key** (String) - Required - Private key value of 16-digit AES after encryption.
- **sign** (String) - Required - Signature value
- **requestBody** (String) - Required - Encrypted request body. Format in JSON before encryption.
```

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

### Integration Process

Source: https://docs.sunrate.com/index

Outlines the step-by-step process for integrating with Sunrate's APIs, from initial documentation review to going live.

```APIDOC
## Integration Process

1.  **Read Developer's Guide and API Documentation**: Understand product capabilities and workflow.
2.  **Consultation**: Discuss business scenarios and requirements with Sunrate.
3.  **UAT Testing**: Test APIs in a User Acceptance Testing environment after configuration.
4.  **Sign Off**: Obtain approval before moving to production.
5.  **Go Live**: Deploy to the production environment and make live API calls.
```

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

### Get FX Trade Quote with SUNRATE API

Source: https://context7.com/context7/sunrate/llms.txt

Obtain a real-time foreign exchange quote for currency conversion. This is used for pure FX trading and locks in the exchange rate for a specified duration. It requires authentication and a JSON payload specifying currency pairs and amounts.

```bash
curl -X POST https://api.sunrate.com/openapi/v3/fxquote/getSingleQuote \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{ \
    "appId": "APP123456789012345678", \
    "msgId": "MSG123456789012345684", \
    "ip": "192.168.1.100", \
    "version": "3.0", \
    "timestamp": "2024-03-20T13:45:22.345", \
    "key": "BASE64_ENCRYPTED_AES_KEY_HERE", \
    "sign": "BASE64_SIGNATURE_HERE", \
    "requestBody": "BASE64_ENCRYPTED_PAYLOAD" \
  }'

# Decrypted requestBody:
# {
#   "buyCurrency": "GBP",
#   "sellCurrency": "USD",
#   "buyAmount": "50000.00",
#   "quoteType": "BUY",
#   "tenorType": "SPOT"
# }

# Decrypted responseBody:
# {
#   "fxQuoteId": "FXQ20240320001",
#   "buyCurrency": "GBP",
#   "sellCurrency": "USD",
#   "buyAmount": "50000.00",
#   "sellAmount": "62812.50",
#   "exchangeRate": "1.25625",
#   "spotRate": "1.25500",
#   "forwardPoints": "0.00125",
#   "validUntil": "2024-03-20T13:46:22.345",
#   "quotedAt": "2024-03-20T13:45:22.567"
# }
```

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

### Onboarding - Query KYC

Source: https://docs.sunrate.com/index

Query the KYC status of a client.

```APIDOC
## GET /openapi/v3/register/get/

### Description
Queries the KYC status for a given client.

### Method
GET

### Endpoint
/openapi/v3/register/get/

### Parameters
#### Query Parameters
- **appId** (String) - Required - Unique identifier of a client assigned by Sunrate
- **msgId** (String) - Required - The request message ID
- **bizId** (String) - Optional - Business ID
- **ip** (String) - Required - User’s browser IP address.
- **version** (String) - Required - Endpoint version. Fixed value “3.0”
- **callbackUrl** (String) - Optional - Callback URL for status updates
- **timestamp** (String) - Required - Timestamp of request, formatted as "yyyy-MM-ddTHH:mm:ss.SSS"
- **key** (String) - Required - Private key value of 16-digit AES after encryption.
- **sign** (String) - Required - Signature value
- **requestBody** (String) - Required - Encrypted request body containing client identifiers. Format in JSON before encryption.
```

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

### Submit KYC for Customer Onboarding using cURL

Source: https://context7.com/context7/sunrate/llms.txt

Registers a new customer by submitting KYC documentation and business information via a POST request. The API validates data and initiates verification, with status updates provided via callback. It requires authentication with an API key and uses a hybrid encryption system.

```bash
curl -X POST https://api.sunrate.com/openapi/v3/register/ \n  -H "Content-Type: application/json" \n  -H "X-API-Key: your_api_key_here" \n  -d '{ \n    "appId": "APP123456789012345678", \n    "msgId": "MSG123456789012345678", \n    "ip": "192.168.1.100", \n    "version": "3.0", \n    "timestamp": "2024-03-15T10:30:45.123", \n    "key": "BASE64_ENCRYPTED_AES_KEY_HERE", \n    "sign": "BASE64_SIGNATURE_HERE", \n    "requestBody": "BASE64_ENCRYPTED_PAYLOAD" \n  }'
```

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

### Submit KYC for Customer Onboarding

Source: https://context7.com/context7/sunrate/llms.txt

Register a new customer by submitting Know Your Customer (KYC) documentation and business information. The system validates the provided data and initiates the verification process. Upon successful submission, SUNRATE will review the application and send status updates via callback.

```APIDOC
## POST /openapi/v3/register/create

### Description
Submits Know Your Customer (KYC) documentation and business information to register a new customer. The system validates the provided data and initiates the verification process. Upon successful submission, SUNRATE will review the application and send status updates via callback.

### Method
POST

### Endpoint
https://api.sunrate.com/openapi/v3/register/create/

### Parameters
#### Request Body
- **appId** (string) - Required - Application ID.
- **msgId** (string) - Required - Message ID.
- **ip** (string) - Required - IP address of the client.
- **version** (string) - Required - API version.
- **timestamp** (string) - Required - Timestamp of the request.
- **key** (string) - Required - Base64 encrypted AES key.
- **sign** (string) - Required - Base64 signature of the request.
- **requestBody** (string) - Required - Base64 encrypted payload containing customer details.

### Request Example
```json
{
  "appId": "APP123456789012345678",
  "msgId": "MSG123456789012345678",
  "ip": "192.168.1.100",
  "version": "3.0",
  "timestamp": "2024-03-15T10:30:45.123",
  "key": "BASE64_ENCRYPTED_AES_KEY_HERE",
  "sign": "BASE64_SIGNATURE_HERE",
  "requestBody": "BASE64_ENCRYPTED_PAYLOAD"
}
```

#### Decrypted requestBody payload example:
```json
{
  "companyName": "Acme Corporation Ltd",
  "registrationNumber": "12345678",
  "country": "SG",
  "businessType": "E_COMMERCE",
  "contactEmail": "finance@acme.com",
  "contactPhone": "+6512345678"
}
```

### Response
#### Success Response (200)
- **msgId** (string) - Message ID.
- **code** (string) - Response code.
- **msg** (string) - Response message.
- **timestamp** (string) - Timestamp of the response.
- **key** (string) - Base64 encrypted AES key for response decryption.
- **sign** (string) - Base64 signature of the response.
- **responseBody** (string) - Base64 encrypted response payload.

#### Response Example
```json
{
  "msgId": "RSP123456789012345678",
  "code": "000000",
  "msg": "Success",
  "timestamp": "2024-03-15T10:30:45.456",
  "key": "BASE64_ENCRYPTED_AES_KEY",
  "sign": "BASE64_SIGNATURE",
  "responseBody": "BASE64_ENCRYPTED_RESPONSE"
}
```

#### Decrypted responseBody:
```json
{
  "customerId": "CUST20240315001",
  "status": "PENDING_REVIEW",
  "submittedAt": "2024-03-15T10:30:45.456"
}
```
```

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

### Onboarding - Update KYC

Source: https://docs.sunrate.com/index

Update existing KYC information for a client.

```APIDOC
## PUT /openapi/v3/register/modify/

### Description
Updates KYC information for an existing client.

### Method
PUT

### Endpoint
/openapi/v3/register/modify/

### Parameters
#### Request Body
- **appId** (String) - Required - Unique identifier of a client assigned by Sunrate
- **msgId** (String) - Required - The request message ID
- **bizId** (String) - Optional - Business ID
- **ip** (String) - Required - User’s browser IP address.
- **version** (String) - Required - Endpoint version. Fixed value “3.0”
- **callbackUrl** (String) - Optional - Callback URL for status updates
- **timestamp** (String) - Required - Timestamp of request, formatted as "yyyy-MM-ddTHH:mm:ss.SSS"
- **key** (String) - Required - Private key value of 16-digit AES after encryption.
- **sign** (String) - Required - Signature value
- **requestBody** (String) - Required - Encrypted request body. Format in JSON before encryption.
```

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

### Book Transfers - Create Transfer

Source: https://docs.sunrate.com/index

Create a new book transfer.

```APIDOC
## POST /openapi/v3/ transfer/create/

### Description
Initiates a new book transfer between accounts.

### Method
POST

### Endpoint
/openapi/v3/ transfer/create/

### Parameters
#### Request Body
- **appId** (String
```

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

### API Overview

Source: https://docs.sunrate.com/index

Provides general information about the API's network protocol, request method, and data format.

```APIDOC
## API Overview

### Network Protocol

-   **Protocol**: HTTP
-   **Request Method**: POST
-   **Data Format**: application/json
-   **Character Encoding**: UTF-8
```

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

### Security Solution

Source: https://docs.sunrate.com/index

Explains the security measures required for API requests, involving AES and RSA encryption, key exchange, and signature generation.

```APIDOC
## Security Solution

**Overview**: Secure API communication using AES and RSA encryption.

### Steps:

1.  **Generate AES Private Key**: Create a random 16-character alphanumeric string.
2.  **RSA Encrypt AES Key**: Encrypt the AES key using Sunrate's public RSA key and Base64 encode it. This becomes the `key` parameter.
3.  **Encrypt Request Body**: Encrypt the operational parameters using AES symmetric encryption and Base64 encode the result. This becomes the `requestBody` parameter.
4.  **Generate Signature**: 
    *   Remove the `sign` field from the request message.
    *   Sort all non-empty parameters in ascending ASCII order.
    *   Concatenate sorted parameters in `key=value` format, joined by `&`.
    *   Sign the concatenated string using your private RSA key (SHA256WithRSA).
    *   Base64 encode the signature. This becomes the `sign` parameter.
5.  **Construct Final Request**: Combine `key`, `requestBody`, and `sign`.

**Note**: RSA key size is 1024-bits.
```

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

### Query Customer KYC Status using cURL

Source: https://context7.com/context7/sunrate/llms.txt

Retrieves the current KYC verification status and details for a registered customer using a POST request. The endpoint returns comprehensive information about the onboarding progress, verification results, and any required additional documentation. Authentication via API key is necessary.

```bash
curl -X POST https://api.sunrate.com/openapi/v3/register/get/ \n  -H "Content-Type: application/json" \n  -H "X-API-Key: your_api_key_here" \n  -d '{ \n    "appId": "APP123456789012345678", \n    "msgId": "MSG123456789012345679", \n    "ip": "192.168.1.100", \n    "version": "3.0", \n    "timestamp": "2024-03-16T14:20:30.789", \n    "key": "BASE64_ENCRYPTED_AES_KEY_HERE", \n    "sign": "BASE64_SIGNATURE_HERE", \n    "requestBody": "BASE64_ENCRYPTED_PAYLOAD" \n  }'
```

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

### Payouts - Download Confirmation

Source: https://docs.sunrate.com/index

Download a confirmation document for a payout transaction.

```APIDOC
## GET /openapi/v3/voucher/transFile/download/

### Description
Downloads a confirmation document for a payout transaction.

### Method
GET

### Endpoint
/openapi/v3/voucher/transFile/download/

### Parameters
#### Query Parameters
- **appId** (String) - Required - Unique identifier of a client assigned by Sunrate
- **msgId** (String) - Required - The request message ID
- **bizId** (String) - Optional - Business ID
- **ip** (String) - Required - User’s browser IP address.
- **version** (String) - Required - Endpoint version. Fixed value “3.0”
- **callbackUrl** (String) - Optional - Callback URL for status updates
- **timestamp** (String) - Required - Timestamp of request, formatted as "yyyy-MM-ddTHH:mm:ss.SSS"
- **key** (String) - Required - Private key value of 16-digit AES after encryption.
- **sign** (String) - Required - Signature value
- **requestBody** (String) - Required - Encrypted request body containing transaction identifier. Format in JSON before encryption.
```

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

### Trade - Create Trade

Source: https://docs.sunrate.com/index

Create a foreign exchange trade transaction.

```APIDOC
## POST /openapi/v3/fxtxn/createFxTxn

### Description
Creates a foreign exchange trade transaction based on a quote.

### Method
POST

### Endpoint
/openapi/v3/fxtxn/createFxTxn

### Parameters
#### Request Body
- **appId** (String) - Required - Unique identifier of a client assigned by Sunrate
- **msgId** (String) - Required - The request message ID
- **bizId** (String) - Optional - Business ID
- **ip** (String) - Required - User’s browser IP address.
- **version** (String) - Required - Endpoint version. Fixed value “3.0”
- **callbackUrl** (String) - Optional - Callback URL for status updates
- **timestamp** (String) - Required - Timestamp of request, formatted as "yyyy-MM-ddTHH:mm:ss.SSS"
- **key** (String) - Required - Private key value of 16-digit AES after encryption.
- **sign** (String) - Required - Signature value
- **requestBody** (String) - Required - Encrypted request body containing trade details and quote information. Format in JSON before encryption.
```

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

### Create and Settle FX Trade with SUNRATE API

Source: https://context7.com/context7/sunrate/llms.txt

Execute a foreign exchange trade in two steps: first create a transaction using a locked quote, then settle it to transfer funds. This ensures rate lock and allows for confirmation before final settlement. Requires API key and detailed JSON payloads for each step.

```bash
# Step 1: Create FX Transaction
curl -X POST https://api.sunrate.com/openapi/v3/fxtxn/createFxTxn \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{ \
    "appId": "APP123456789012345678", \
    "msgId": "MSG123456789012345685", \
    "bizId": "BIZ20240320001", \
    "ip": "192.168.1.100", \
    "version": "3.0", \
    "timestamp": "2024-03-20T13:46:00.123", \
    "key": "BASE64_ENCRYPTED_AES_KEY_HERE", \
    "sign": "BASE64_SIGNATURE_HERE", \
    "requestBody": "BASE64_ENCRYPTED_PAYLOAD" \
  }'

# Decrypted requestBody for creation:
# {
#   "fxQuoteId": "FXQ20240320001",
#   "accountId": "ACC20240315001",
#   "reference": "FX_HEDGE_Q1_2024"
# }

# Decrypted responseBody:
# {
#   "fxTxnId": "FXTXN20240320001",
#   "status": "PENDING_SETTLEMENT",
#   "buyCurrency": "GBP",
#   "sellCurrency": "USD",
#   "buyAmount": "50000.00",
#   "sellAmount": "62812.50",
#   "exchangeRate": "1.25625",
#   "expiresAt": "2024-03-20T14:46:00.000"
# }

# Step 2: Settle FX Transaction
curl -X POST https://api.sunrate.com/openapi/v3/fxtxn/dealFxTxn \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{ \
    "appId": "APP123456789012345678", \
    "msgId": "MSG123456789012345686", \
    "ip": "192.168.1.100", \
    "version": "3.0", \
    "timestamp": "2024-03-20T13:47:30.456", \
    "key": "BASE64_ENCRYPTED_AES_KEY_HERE", \
    "sign": "BASE64_SIGNATURE_HERE", \
    "requestBody": "BASE64_ENCRYPTED_PAYLOAD" \
  }'

# Decrypted requestBody for settlement:
# {
#   "fxTxnId": "FXTXN20240320001"
# }

# Decrypted responseBody:
# {
#   "fxTxnId": "FXTXN20240320001",
#   "status": "SETTLED",
#   "settledAt": "2024-03-20T13:47:30.789",
#   "valueDate": "2024-03-22T00:00:00.000"
# }
```

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

### Payouts - Create Payout

Source: https://docs.sunrate.com/index

Create a new payout transaction.

```APIDOC
## POST /openapi/v3/trade/create/

### Description
Initiates a new payout transaction.

### Method
POST

### Endpoint
/openapi/v3/trade/create/

### Parameters
#### Request Body
- **appId** (String) - Required - Unique identifier of a client assigned by Sunrate
- **msgId** (String) - Required - The request message ID
- **bizId** (String) - Optional - Business ID
- **ip** (String) - Required - User’s browser IP address.
- **version** (String) - Required - Endpoint version. Fixed value “3.0”
- **callbackUrl** (String) - Optional - Callback URL for status updates
- **timestamp** (String) - Required - Timestamp of request, formatted as "yyyy-MM-ddTHH:mm:ss.SSS"
- **key** (String) - Required - Private key value of 16-digit AES after encryption.
- **sign** (String) - Required - Signature value
- **requestBody** (String) - Required - Encrypted request body containing payout details. Format in JSON before encryption.
```

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

### Query Customer KYC Status

Source: https://context7.com/context7/sunrate/llms.txt

Retrieve the current KYC verification status and details for a registered customer. This endpoint returns comprehensive information about the onboarding progress, verification results, and any required additional documentation.

```APIDOC
## POST /openapi/v3/register/get

### Description
Retrieves the current KYC verification status and details for a registered customer. This endpoint returns comprehensive information about the onboarding progress, verification results, and any required additional documentation.

### Method
POST

### Endpoint
https://api.sunrate.com/openapi/v3/register/get/

### Parameters
#### Request Body
- **appId** (string) - Required - Application ID.
- **msgId** (string) - Required - Message ID.
- **ip** (string) - Required - IP address of the client.
- **version** (string) - Required - API version.
- **timestamp** (string) - Required - Timestamp of the request.
- **key** (string) - Required - Base64 encrypted AES key.
- **sign** (string) - Required - Base64 signature of the request.
- **requestBody** (string) - Required - Base64 encrypted payload containing customer ID.

### Request Example
```json
{
  "appId": "APP123456789012345678",
  "msgId": "MSG123456789012345679",
  "ip": "192.168.1.100",
  "version": "3.0",
  "timestamp": "2024-03-16T14:20:30.789",
  "key": "BASE64_ENCRYPTED_AES_KEY_HERE",
  "sign": "BASE64_SIGNATURE_HERE",
  "requestBody": "BASE64_ENCRYPTED_PAYLOAD"
}
```

#### Decrypted requestBody:
```json
{
  "customerId": "CUST20240315001"
}
```

### Response
#### Success Response (200)
- **msgId** (string) - Message ID.
- **code** (string) - Response code.
- **msg** (string) - Response message.
- **timestamp** (string) - Timestamp of the response.
- **key** (string) - Base64 encrypted AES key for response decryption.
- **sign** (string) - Base64 signature of the response.
- **responseBody** (string) - Base64 encrypted response payload.

#### Response Example
```json
{
  "msgId": "RSP123456789012345679",
  "code": "000000",
  "msg": "Success",
  "timestamp": "2024-03-16T14:20:30.999",
  "key": "BASE64_ENCRYPTED_AES_KEY",
  "sign": "BASE64_SIGNATURE",
  "responseBody": "BASE64_ENCRYPTED_RESPONSE"
}
```

#### Decrypted responseBody:
```json
{
  "customerId": "CUST20240315001",
  "companyName": "Acme Corporation Ltd",
  "status": "APPROVED",
  "approvedAt": "2024-03-16T09:15:22.000",
  "kycLevel": "STANDARD",
  "accountCurrencies": ["USD", "EUR", "GBP", "SGD"]
}
```
```

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

### Query Account Balances - Bash

Source: https://context7.com/context7/sunrate/llms.txt

Retrieves the current available, pending, and reserved balances for all currency accounts associated with a given customer or merchant account. Requires an API key and encrypted payload.

```bash
curl -X POST https://api.sunrate.com/openapi/v3/balance/list/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{ \
    "appId": "APP123456789012345678", \
    "msgId": "MSG123456789012345688", \
    "ip": "192.168.1.100", \
    "version": "3.0", \
    "timestamp": "2024-03-22T09:30:45.123", \
    "key": "BASE64_ENCRYPTED_AES_KEY_HERE", \
    "sign": "BASE64_SIGNATURE_HERE", \
    "requestBody": "BASE64_ENCRYPTED_PAYLOAD" \
  }'

# Decrypted requestBody:
# {
#   "accountId": "ACC20240315001"
# }

# Decrypted responseBody:
# {
#   "accountId": "ACC20240315001",
#   "accountName": "Acme Corporation Ltd",
#   "balances": [
#     {
#       "currency": "USD",
#       "availableBalance": "95025.00",
#       "pendingBalance": "2500.00",
#       "reservedBalance": "1000.00",
#       "totalBalance": "98525.00",
#       "lastUpdated": "2024-03-22T09:30:45.345"
#     },
#     {
#       "currency": "EUR",
#       "availableBalance": "45230.75",
#       "pendingBalance": "0.00",
#       "reservedBalance": "0.00",
#       "totalBalance": "45230.75",
#       "lastUpdated": "2024-03-22T09:30:45.345"
#     },
#     {
#       "currency": "GBP",
#       "availableBalance": "50000.00",
#       "pendingBalance": "0.00",
#       "reservedBalance": "0.00",
#       "totalBalance": "50000.00",
#       "lastUpdated": "2024-03-22T09:30:45.345"
#     }
#   ]
# }
```

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

### Collections - Query Collections

Source: https://docs.sunrate.com/index

Query a list of collections.

```APIDOC
## GET /openapi/v3/transin/globalCollectionAccount/list/

### Description
Retrieves a list of collections based on specified criteria.

### Method
GET

### Endpoint
/openapi/v3/transin/globalCollectionAccount/list/

### Parameters
#### Query Parameters
- **appId** (String) - Required - Unique identifier of a client assigned by Sunrate
- **msgId** (String) - Required - The request message ID
- **bizId** (String) - Optional - Business ID
- **ip** (String) - Required - User’s browser IP address.
- **version** (String) - Required - Endpoint version. Fixed value “3.0”
- **callbackUrl** (String) - Optional - Callback URL for status updates
- **timestamp** (String) - Required - Timestamp of request, formatted as "yyyy-MM-ddTHH:mm:ss.SSS"
- **key** (String) - Required - Private key value of 16-digit AES after encryption.
- **sign** (String) - Required - Signature value
- **requestBody** (String) - Required - Encrypted request body containing query parameters. Format in JSON before encryption.
```

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

### Recipients - Create Recipient

Source: https://docs.sunrate.com/index

Create a new recipient for payouts.

```APIDOC
## POST /openapi/v3/beneficiary/create/

### Description
Creates a new recipient profile for making payouts.

### Method
POST

### Endpoint
/openapi/v3/beneficiary/create/

### Parameters
#### Request Body
- **appId** (String) - Required - Unique identifier of a client assigned by Sunrate
- **msgId** (String) - Required - The request message ID
- **bizId** (String) - Optional - Business ID
- **ip** (String) - Required - User’s browser IP address.
- **version** (String) - Required - Endpoint version. Fixed value “3.0”
- **callbackUrl** (String) - Optional - Callback URL for status updates
- **timestamp** (String) - Required - Timestamp of request, formatted as "yyyy-MM-ddTHH:mm:ss.SSS"
- **key** (String) - Required - Private key value of 16-digit AES after encryption.
- **sign** (String) - Required - Signature value
- **requestBody** (String) - Required - Encrypted request body containing recipient details. Format in JSON before encryption.
```

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

### JavaScript: Implement Encrypted and Signed API Request/Response Workflow

Source: https://context7.com/context7/sunrate/llms.txt

This snippet provides a complete JavaScript implementation for encrypting API requests and decrypting responses using AES and RSA. It includes functions for key generation, encryption, decryption, signing, and verification. Dependencies include the Node.js 'crypto' module. It takes business request data and merchant/Sunrate keys as input and outputs signed, encrypted request parameters, and processes signed, encrypted responses.

```javascript
const crypto = require('crypto');

// Generate 16-character random AES key
function generateAESKey() {
  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
  let aesKey = '';
  for (let i = 0; i < 16; i++) {
    aesKey += chars.charAt(Math.floor(Math.random() * chars.length));
  }
  return aesKey;
}

// AES encrypt request body
function encryptRequestBody(requestData, aesKey) {
  const cipher = crypto.createCipheriv('aes-128-ecb', aesKey, null);
  let encrypted = cipher.update(JSON.stringify(requestData), 'utf8', 'base64');
  encrypted += cipher.final('base64');
  return encrypted;
}

// RSA encrypt AES key with SUNRATE public key
function encryptAESKey(aesKey, sunratePublicKey) {
  const encrypted = crypto.publicEncrypt(
    {
      key: sunratePublicKey,
      padding: crypto.constants.RSA_PKCS1_PADDING
    },
    Buffer.from(aesKey, 'utf8')
  );
  return encrypted.toString('base64');
}

// Generate signature
function generateSignature(params, merchantPrivateKey) {
  // Remove sign field and sort parameters
  const sortedParams = Object.keys(params)
    .filter(key => key !== 'sign' && params[key] !== null && params[key] !== '')
    .sort()
    .map(key => `${key}=${params[key]}`)
    .join('&');

  const sign = crypto.createSign('RSA-SHA256');
  sign.update(sortedParams, 'utf8');
  const signature = sign.sign(merchantPrivateKey, 'base64');
  return signature;
}

// Complete request construction example
function buildAPIRequest() {
  const merchantPrivateKey = `-----BEGIN RSA PRIVATE KEY-----
YOUR_MERCHANT_PRIVATE_KEY_HERE
-----END RSA PRIVATE KEY-----`;

  const sunratePublicKey = `-----BEGIN PUBLIC KEY-----
SUNRATE_PUBLIC_KEY_HERE
-----END PUBLIC KEY-----`;

  // Business request data
  const requestData = {
    beneficiaryId: "BEN20240317001",
    sourceAccount: "ACC20240315001",
    sourceCurrency: "USD",
    targetCurrency: "EUR",
    amount: "10000.00",
    paymentPurpose: "Payment for invoice INV-2024-0318"
  };

  // Generate AES key and encrypt request body
  const aesKey = generateAESKey(); // e.g., "aB3dE5fG7hJ9kL1m"
  const encryptedBody = encryptRequestBody(requestData, aesKey);
  const encryptedKey = encryptAESKey(aesKey, sunratePublicKey);

  // Prepare public parameters
  const publicParams = {
    appId: "APP123456789012345678",
    msgId: "MSG" + Date.now() + Math.random().toString(36).substr(2, 9),
    bizId: "BIZ" + Date.now(),
    ip: "192.168.1.100",
    version: "3.0",
    callbackUrl: "https://merchant.example.com/webhooks/payout-status",
    timestamp: new Date().toISOString().replace('Z', '').slice(0, -3),
    key: encryptedKey,
    requestBody: encryptedBody
  };

  // Generate signature
  const signature = generateSignature(publicParams, merchantPrivateKey);
  publicParams.sign = signature;

  return publicParams;
}

// Decrypt and verify response
function processAPIResponse(response, merchantPrivateKey, sunratePublicKey) {
  // Verify signature
  const { sign, ...paramsWithoutSign } = response;
  const sortedParams = Object.keys(paramsWithoutSign)
    .filter(key => paramsWithoutSign[key] !== null && paramsWithoutSign[key] !== '')
    .sort()
    .map(key => `${key}=${paramsWithoutSign[key]}`)
    .join('&');

  const verify = crypto.createVerify('RSA-SHA256');
  verify.update(sortedParams, 'utf8');
  const isValid = verify.verify(sunratePublicKey, sign, 'base64');

  if (!isValid) {
    throw new Error('Signature verification failed');
  }

  // Decrypt AES key
  const aesKey = crypto.privateDecrypt(
    {
      key: merchantPrivateKey,
      padding: crypto.constants.RSA_PKCS1_PADDING
    },
    Buffer.from(response.key, 'base64')
  ).toString('utf8');

  // Decrypt response body
  const decipher = crypto.createDecipheriv('aes-128-ecb', aesKey, null);
  let decrypted = decipher.update(response.responseBody, 'base64', 'utf8');
  decrypted += decipher.final('utf8');

  return {
    ...response,
    decryptedBody: JSON.parse(decrypted),
    signatureValid: true
  };
}

// Usage example
const request = buildAPIRequest();
console.log('Encrypted Request:', JSON.stringify(request, null, 2));

// Simulated API response
const apiResponse = {
  msgId: "RSP123456789012345678",
  code: "000000",
  msg: "Success",
  timestamp: "2024-03-18T09:30:45.890",
  key: "BASE64_ENCRYPTED_AES_KEY",
  sign: "BASE64_SIGNATURE",
  responseBody: "BASE64_ENCRYPTED_RESPONSE"
};

// Note: merchantPrivateKey and sunratePublicKey are placeholders and need to be defined.
// For a real scenario, these would be loaded securely.
// const merchantPrivateKey = `-----BEGIN RSA PRIVATE KEY-----\nYOUR_MERCHANT_PRIVATE_KEY_HERE\n-----END RSA PRIVATE KEY-----`;
// const sunratePublicKey = `-----BEGIN PUBLIC KEY-----\nSUNRATE_PUBLIC_KEY_HERE\n-----END PUBLIC KEY-----`;

// try {
//   const decryptedResponse = processAPIResponse(
//     apiResponse,
//     merchantPrivateKey, // Replace with actual key
//     sunratePublicKey    // Replace with actual key
//   );
//   console.log('Decrypted Response:', JSON.stringify(decryptedResponse, null, 2));
// } catch (error) {
//   console.error('Error processing response:', error);
// }
```

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

### Create International Payout - Bash

Source: https://context7.com/context7/sunrate/llms.txt

Executes a cross-border payment to a registered beneficiary using a quote. Debits sender, converts currency if needed, and initiates transfer. Requires API key, quote ID, and encrypted payload. Status updates via callback URL.

```bash
curl -X POST https://api.sunrate.com/openapi/v3/trade/create/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "appId": "APP123456789012345678",
    "msgId": "MSG123456789012345682",
    "bizId": "BIZ20240318001",
    "ip": "192.168.1.100",
    "version": "3.0",
    "callbackUrl": "https://merchant.example.com/webhooks/payout-status",
    "timestamp": "2024-03-18T09:30:45.678",
    "key": "BASE64_ENCRYPTED_AES_KEY_HERE",
    "sign": "BASE64_SIGNATURE_HERE",
    "requestBody": "BASE64_ENCRYPTED_PAYLOAD"
  }'

# Decrypted requestBody:
# {
#   "quoteId": "QTE20240318001",
#   "beneficiaryId": "BEN20240317001",
#   "sourceAccount": "ACC20240315001",
#   "paymentPurpose": "Payment for invoice INV-2024-0318",
#   "purposeCode": "GOODS_PAYMENT",
#   "invoiceNumber": "INV-2024-0318",
#   "merchantReference": "ORDER-12345"
# }

# Decrypted responseBody:
# {
#   "tradeId": "TXN20240318001",
#   "status": "PROCESSING",
#   "sourceCurrency": "USD",
#   "targetCurrency": "EUR",
#   "sourceAmount": "10000.00",
#   "targetAmount": "9245.00",
#   "exchangeRate": "0.9245",
#   "fee": "25.00",
#   "estimatedArrival": "2024-03-20T17:00:00.000",
#   "createdAt": "2024-03-18T09:30:45.890"
# }
```

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

### Payouts - Query Payouts

Source: https://docs.sunrate.com/index

Query a list of payout transactions.

```APIDOC
## GET /openapi/v3/trade/list/

### Description
Retrieves a list of payout transactions.

### Method
GET

### Endpoint
/openapi/v3/trade/list/

### Parameters
#### Query Parameters
- **appId** (String) - Required - Unique identifier of a client assigned by Sunrate
- **msgId** (String) - Required - The request message ID
- **bizId** (String) - Optional - Business ID
- **ip** (String) - Required - User’s browser IP address.
- **version** (String) - Required - Endpoint version. Fixed value “3.0”
- **callbackUrl** (String) - Optional - Callback URL for status updates
- **timestamp** (String) - Required - Timestamp of request, formatted as "yyyy-MM-ddTHH:mm:ss.SSS"
- **key** (String) - Required - Private key value of 16-digit AES after encryption.
- **sign** (String) - Required - Signature value
- **requestBody** (String) - Required - Encrypted request body containing query parameters. Format in JSON before encryption.
```

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

### Query Exchange Rate for Payout - Bash

Source: https://context7.com/context7/sunrate/llms.txt

Retrieves real-time foreign exchange quotes for cross-border payments. Requires API key and encrypted payload. Outputs include exchange rates, fees, and total debit amount. Quotes are valid for a short period.

```bash
curl -X POST https://api.sunrate.com/openapi/v3/trade/queryPrice/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "appId": "APP123456789012345678",
    "msgId": "MSG123456789012345681",
    "ip": "192.168.1.100",
    "version": "3.0",
    "timestamp": "2024-03-18T09:30:00.123",
    "key": "BASE64_ENCRYPTED_AES_KEY_HERE",
    "sign": "BASE64_SIGNATURE_HERE",
    "requestBody": "BASE64_ENCRYPTED_PAYLOAD"
  }'

# Decrypted requestBody:
# {
#   "sourceCurrency": "USD",
#   "targetCurrency": "EUR",
#   "amount": "10000.00",
#   "amountType": "SOURCE",
#   "purposeCode": "GOODS_PAYMENT"
# }

# Decrypted responseBody:
# {
#   "quoteId": "QTE20240318001",
#   "sourceCurrency": "USD",
#   "targetCurrency": "EUR",
#   "sourceAmount": "10000.00",
#   "exchangeRate": "0.9245",
#   "targetAmount": "9245.00",
#   "fee": "25.00",
#   "totalDebit": "10025.00",
#   "validUntil": "2024-03-18T09:31:00.000",
#   "rateType": "MARKET"
# }
```
Tokens:
Raw