Execute a Programmatic Payment

This guide provides step by step instructions for delivering a programmatic payment to a smart contract.

1. Ensure you've followed steps in Create a Community Splits Contract Using SHARE UI to obtain a smart contract ID which will receive and distribute payments.

2. Ensure you've funded your business account by Prepaying for API Credits. You'll need at least $1.00 USD in credits to complete this guide.

3. Execute a payout using the cURL command below with your contract ID as the recipient_id .

cURL

curl -v -X POST 'https://share-ddn.formless.xyz/v1' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $API_KEY" \
-d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "payouts",
    "params": {
        "idempotency_key" : "0af4989b-96fe-4203-9f40-2b58c9f6e078",
        "recipient_type": "smart_contract",
        "recipient_id": "32843127-d5d9-41d7-b1ad-508de4f86693",
        "amount": {
            "value" : 1.00,
            "currency" : "USD"
        }
    }
}'

The idempotency_key is an optional value that guarantees calls execute only once, e.g. in the event of a retry within your system. In production you should always supply a unique UUID V4 value here.

Response

{
    "jsonrpc": "2.0",
    "id": "2",
    "result": {
        "batch_id": "02473ddd-c09c-475f-a120-7d771b6ae43e",
        "status": "pending",
        "message": "Your payouts are being processed and you will receive an email upon completion."
    }
}

1. Query the server to check on the status of the payout using the batch_id.

cURL

curl -v -X POST 'https://share-ddn.formless.xyz/v1' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $API_KEY" \
--data '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "payouts",
    "params": {
        "batch_id" : "89de4f6d-a8e5-4808-9c29-ebac29dec4cb"
    }
}'

Response

{
    "jsonrpc": "2.0",
    "id": "1",
    "result": {
        "details": {
            "contract_address": "0xb1303e1cAffC4A0dfA4D67227D53aA384d7f962d",
            "network_id": 137,
            "amount_usd": 10.00
        },
        "submitter": "00000003XG",
        "payout_batch_id": "89de4f6d-a8e5-4808-9c29-ebac29dec4cb",
        "status": "complete"
    }
}

1. Done! You've now distributed realtime payouts to a smart contract, which will instantly route payments to payees. Over time, even as payees change within the contract, your system will continue to distribute payments to the correct stakeholders.

Here are a few things to keep in mind due to the nature of blockchain technology:

Payments made using the SHARE API are instant, irreversible and final. Payments should not be made until the API caller is confident that there is no fraud on the metric used to determine the payment amount.

Splits contracts used as a payout recipient require verified identities. In order to join splits and receive payments, payees must verify using email and SMS based 2FA.

Payment conversion to local currencies and tax compliance is done in partnership with Beam. Payees cash out using a process known as off-ramping in partnership with Beam. Beam converts cryptocurrency into USD securely, efficiently, and instantly sends funds to a bank account.