Create Sub-Payee

If you would like to set up sub-payees for your application, please follow the instructions below or refer to our guide.

Endpoint

POST https://api.bindpay.xyz/v1/create-subpayee

Headers

Header	Value	Description
Content-Type	application/json	The content type of the request body
x-api-key	Your API key	The subpayee creation API key of the parent business

To create sub-payees you first need to generate a sub-payee creation API key within the sub-payee management section of the developer portal - app.bindpay.xyz

Request Body

Field	Type	Description
name	string	The name of the subpayee
toChain	string	The chain ID of the destination blockchain
toToken	string	The token address on the destination blockchain
toAddress	string	The wallet address of the subpayee

Notes:

• All fields in the request body are required.

• The toChain, toToken, and toAddress fields define the settlement details for the subpayee.

• Ensure the toAddress is a valid wallet address on the specified blockchain.

• Pay special attention to the note about the subpayee creation API key, as it's different from the regular API key.

Example Request

cURL

curl -X POST "https://api.bindpay.xyz/v1/create-subpayee" \
     -H "Content-Type: application/json" \
     -H "x-api-key: your_generate_subpayee_api_key_here" \
     -d '{
       "name": "Leroy Jenkins",
       "toChain": "1",
       "toToken": "ETH",
       "toAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44b"
     }'

Python

import requests

url = "https://api.bindpay.xyz/v1/create-subpayee"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "your_generate_subpayee_api_key_here"
}
data = {
    "name": "Leroy Jenkins",
    "toChain": "1",
    "toToken": "ETH",
    "toAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44b"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Rust

use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let url = "https://api.bindpay.xyz/v1/create-subpayee";
    let client = Client::new();

    let response = client.post(url)
        .header("Content-Type", "application/json")
        .header("x-api-key", "your_generate_subpayee_api_key_here")
        .json(&json!({
            "name": "Leroy Jenkins",
            "toChain": "1",
            "toToken": "ETH",
            "toAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44b"
        }))
        .send()
        .await?;

    println!("{}", response.text().await?);
    Ok(())
}

Ruby

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.bindpay.xyz/v1/create-subpayee')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri, 
    'Content-Type' => 'application/json',
    'x-api-key' => 'your_generate_subpayee_api_key_here'
)
request.body = {
    name: 'Leroy Jenkins',
    toChain: '1',
    toToken: 'ETH',
    toAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44b'
}.to_json

response = http.request(request)
puts response.body

JavaScript

const axios = require('axios');

const url = 'https://api.bindpay.xyz/v1/create-subpayee';
const headers = {
    'Content-Type': 'application/json',
    'x-api-key': 'your_generate_subpayee_api_key_here'
};
const data = {
    name: 'Leroy Jenkins',
    toChain: '1',
    toToken: 'ETH',
    toAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44b'
};

axios.post(url, data, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error('Error:', error));

TypeScript

import axios from 'axios';

const url = 'https://api.bindpay.xyz/v1/create-subpayee';
const headers = {
    'Content-Type': 'application/json',
    'x-api-key': 'your_generate_subpayee_api_key_here'
};
const data = {
    name: 'Leroy Jenkins',
    toChain: '1',
    toToken: 'ETH',
    toAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44b'
};

axios.post(url, data, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error('Error:', error));

Notes:

• This curl command demonstrates how to make the API call from the command line.

• Replace your-subpayee-creation-api-key-here with the actual subpayee creation API key.

• The example uses Ethereum (chain ID 1) and USDC token address as placeholders.

Successful Response

{
  "message": "Subpayee created successfully",
  "apiKey": "generated-api-key-for-subpayee"
}

Notes:

• The response includes a newly generated API key specific to the created subpayee. Use this key when requesting quotes to direct payments to the sub-payees desired settlement details.

• This API key should be securely stored as it represents the sub-payee - get in touch for any integration questions - [email protected].

Error Response

Status Code	Error Type	Description
400	Bad Request	The request was invalid. This occurs when the API key is missing or when required fields in the request body are missing.
401	Unauthorized	The provided subpayee creation API key is invalid.
404	Not Found	The parent business associated with the provided subpayee creation API key was not found.
409	Conflict	A subpayee with the same name already exists for this parent business.
422	Unprocessable Entity	The request was well-formed but contains invalid data (e.g., invalid blockchain address).
429	Too Many Requests	The user has sent too many requests in a given amount of time.
500	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.

Notes:

• Error responses use standard HTTP status codes for easy interpretation.

• The 400 status code indicates client-side errors (e.g., missing fields).

• The 404 status code specifically indicates that the parent business was not found.

Any further questions - feel free to explore the rest of our documentation or get in touch at [email protected]!