Cowdidocs
API ReferenceInvoice financing

Register a merchant payout instrument

POST
/v1/financing/merchants/{merchantId}/bank-details

Creates an unverified payout instrument. Requires the dedicated merchant:financing.bank_details:write permission, distinct from invoice/document writes.

Authorization

oauth2
AuthorizationBearer <token>

Create a client with POST /v1/oauth/clients, then exchange its credentials for an access token. AUTHORIZATION_CODE clients act on behalf of a signed-in user and always use PKCE; CLIENT_CREDENTIALS clients act as themselves. A client may only be granted scopes its creator already holds — read the grantable list from GET /v1/oauth/clients/scopes.

In: header

Path Parameters

merchantId*string

Canonical sales-app merchant id, shared with Core. Legacy ids remain readable.

Length1 <= length <= 255

Request Body

application/json

Payout instrument to register for a merchant: a PAY_BILL, BUY_GOODS, or BANK_ACCOUNT.

Payout instrument to register for a merchant: a PAY_BILL, BUY_GOODS, or BANK_ACCOUNT.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/financing/merchants/01JZQ5W7M5Y83M6F1D6E0A2K8N/bank-details" \  -H "Content-Type: application/json" \  -d '{    "type": "PAY_BILL",    "paybill_number": "string",    "account_number": "string"  }'
{  "type": "PAY_BILL",  "paybill_number": "247247",  "account_number": "INV-2026-0001",  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "is_verified": true,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}
{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}
{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}
{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}
{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}
{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}
{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}
{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}

List a merchant’s payout instruments GET

Returns a merchant’s payout instruments, newest first; the result is a small bounded set and is not paginated. Requires `merchant:financing.bank_details:read` on the merchant; an organization-scoped role can grant that same permission across every merchant it manages. An impersonated caller sees the account number and account holder name masked.

Remove a merchant payout instrument DELETE

Removes a payout instrument the merchant no longer uses, freeing a slot under the organization’s payout-instrument limit. Requires the same `merchant:financing.bank_details:write` permission as registering one. Loan applications already submitted are unaffected: they carry their own copy of the destination they were submitted with.