Gyvar docs
API reference v1Payouts

Pay a beneficiary in local currency

Converts from your Bitcoin or stablecoin balance and pays out in local currency, in one call. `amount_minor` is what leaves your wallet. Set `min_settlement_amount_minor` to have the payout refused, with nothing debited, if the recipient would get less (`slippage_exceeded`). Pay a saved `beneficiary_id`, or a new `destination`. Some corridors also need a `sender`.

POST
/payouts

Authorization

KeyID Timestamp Nonce Signature
X-Gyvar-Key<token>

Your key id, gyv_k_live_... or gyv_k_sandbox_....

In: header

X-Gyvar-Timestamp<token>

Unix seconds. Must be within 5 minutes of our clock.

In: header

X-Gyvar-Nonce<token>

A unique value per request. Replays are rejected.

In: header

X-Gyvar-Signature<token>

Ed25519 signature over the canonical string. See the Signing guide.

In: header

Header Parameters

Idempotency-Key*string

Unique per payment. Retrying with the same key returns the same order.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

beneficiary_id?string

A saved destination. Send this or destination, not both.

Formatuuid
destination?

A new payee's account details, instead of beneficiary_id. It is saved as a destination and checked like one, including name lookup where the corridor has it.

asset*string
amount_minor*integer

Wallet debit, in the asset's minor units.

min_settlement_amount_minor?integer

Optional. The least the recipient must receive, in the corridor currency's minor units, or the payout is refused.

reason?string
sender?

Who the payout is on behalf of, for corridors that require it - the corridor's sender field lists the keys. Omit it to use your own business details. For Rwanda: {"account_name": "Aline Uwase", "country": "RW", "address": "KG 7 Ave, Kigali"}.

customer_id?string

Optional. The customer this payout is for. A new destination is saved under them.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/payouts" \  -H "Idempotency-Key: 9f1c2f7e-3a55-4a1f-9d3f-6f6a0f4e51b2" \  -H "Content-Type: application/json" \  -d '{    "asset": "USDC",    "amount_minor": 10500000  }'
{  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "reference": "string",    "status": "successful",    "currency": "string",    "amount": "string",    "amount_minor": "string",    "fee": "string",    "fee_minor": "string",    "created_at": "2019-08-24T14:15:22Z"  }}

Payouts

Pay out in local currency to mobile money and bank accounts, from a Bitcoin or stablecoin balance.

Look up an account

Returns the name on a bank or mobile-money account, so you can confirm who you are paying before you pay. Available where the corridor's `name_enquiry` is true. Needs a key with the `money` capability.