Payouts

Newest first, cursor-paginated. Requires a PAYOUT-class key.

Query Parameters

Response Body

Send coin from your business wallet to a Coinland customer. Requires a PAYOUT-class key.

This is synchronous. A 201 means the money has moved — your business wallet is debited debited_amount and the recipient's spot balance is credited exactly amount, in one transaction, before the response is written. There is no pending state to poll.

Name the recipient in exactly ONE of two ways (sending both, or neither, is PAY_RECIPIENT_INVALID):

• payer_id — the opaque handle carried on every payment that customer has made to you. This is the ordinary path: you already hold the handle, nothing has to be looked up, and no email is sent over the wire.
• recipient_token + recipient_confirm — the email path, for paying someone who has never paid you. Call POST /payouts/recipients/lookup first, show the masked_name it returns to a human, and echo that string back VERBATIM as recipient_confirm. Available only if Coinland has set your payout scope to any.

The fee is yours: the recipient receives exactly amount and your wallet is debited amount + fee_amount, at the same tier rate your payments are charged at. Retrying with the same reference_id and an identical payload returns the original payout with 201 — it does not pay twice.

Response Body

Turn an email address into a short-lived, signed recipient_token you can spend on POST /payouts. Requires a PAYOUT-class key, and is open only to merchants whose payout scope Coinland has set to any — otherwise it answers MERCHANT_PAYOUTS_DISABLED (403). An address that cannot be paid — unknown, ineligible, or not fully verified — answers PAY_RECIPIENT_INVALID (422), one code for every such case so the endpoint cannot be used to probe who has an account.

The token is valid for 10 minutes, is bound to the merchant that minted it, and carries the resolved recipient inside its signature — the email itself never rides the payout request.

masked_name is a recognition aid, not an identification: show it to a human, have them confirm it is who they meant, and pass it back as recipient_confirm. A payout whose confirm does not match is refused.

This endpoint is deliberately not an address-existence oracle. An unknown address, a disabled account and an account that has not completed identity verification all answer the same PAY_RECIPIENT_INVALID, and lookups are metered per merchant.

Response Body

The authoritative record — what payout.completed tells you to come read. Requires a PAYOUT-class key.

Path Parameters

Response Body

Return coin to the customer who paid you. Requires a PAYOUT-class key. Like a payout, it settles synchronously and answers with the same object, under kind: "refund".

You name only the amount. The recipient and the currency come from the payment row, never from the request — a refund travels back the way the money came, and there is no field with which to send it somewhere else.

Partial refunds are allowed and can be repeated; what is capped is the CUMULATIVE total, at the payment's charged_amount. Going over is PAY_REFUND_EXCEEDS_PAYMENT (422).

Refunds are fee-exempt — fee_amount is "0" and debited_amount == amount. Coinland keeps the fee charged on the original payment and takes nothing further, so refunding costs you the coin and nothing else. The original fee is not returned.

Path Parameters

Response Body