Payment instruments

Manage bank account payment instruments for your sub-entities.

Get payment instrument details

Retrieve the details of a specific payment instrument used for sub-entity payouts.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
entityId
required
string

The sub-entity's ID.

Example: ent_w4jelhppmfiufdnatam37wrfc4
id
required
string

The payment instrument's ID.

Example: ppi_qn4nis4k3ykpzzu7cvtuvhqqga
Responses
200

Payment instrument details

400

Bad Request

401

Unauthorized

get/accounts/entities/{entityId}/payment-instruments/{id}
Request samples
// For more information please refer to https://github.com/checkout/checkout-sdk-go
import (
	"github.com/checkout/checkout-sdk-go"
	"github.com/checkout/checkout-sdk-go/configuration"
)

// API Keys
api, err := checkout.
			Builder().
			StaticKeys().
			WithSecretKey("secret_key").
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
                        WithEnvironmentSubdomain("{prefix}"). // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
			Build()
if err != nil {
	return nil, err
}

// OAuth
api, err := checkout.
			Builder().
			OAuth().
			WithClientCredentials("client_id", "client_secret").
			WithScopes([]string{configuration.Accounts}).
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
                        WithEnvironmentSubdomain("{prefix}"). // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
			Build()
if err != nil {
	return nil, err
}

response, err := api.Accounts.RetrievePaymentInstrumentDetails("entity_id", "payment_instrument_id")
if err != nil {
	return nil, err
}

return response, nil
Response samples
application/json
{
  • "id": "ppi_qn4nis4k3ykpzzu7cvtuvhqqga",
  • "label": "Bob's Bank Account",
  • "type": "bank_account",
  • "currency": "GBP",
  • "country": "GB",
  • "document": {
    },
  • "status": "verified",
  • "instrument_id": "src_pdasnoaxrtoevpyh3opgaxcrti"
}

Update payment instrument details

Set an existing payment instrument as default. This will make it the destination instrument when a scheduled payout is made. You can also update the label of a payment instrument.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
entityId
required
string

The sub-entity's ID.

Example: ent_w4jelhppmfiufdnatam37wrfc4
id
required
string

The payment instrument's ID.

Example: ppi_qn4nis4k3ykpzzu7cvtuvhqqga
Request Body schema: application/json
required
label
string (Label) [ 1 .. 50 ] characters

A reference that you can use to identify the payment instrument.

default
boolean (Default)
Deprecated

For ad-hoc payouts, the payment instrument is explicitly specified in the payout request. For scheduled payouts, the first payment instrument created for a given currency will be used for that currency's payout schedule. To change the payment instrument associated with a payout schedule, update the payout schedule. (Deprecated) Specifies whether the payment instrument should be set as the default payout destination.

object
Responses
200

Payment instrument updated successfully

401

Unauthorized

422

Unprocessable entity

428

Precondition required

patch/accounts/entities/{entityId}/payment-instruments/{id}
Request samples
application/json
{
  • "label": "Peter's Personal Account",
  • "default": true,
  • "headers": {
    }
}
Response samples
application/json
{}

Add a payment instrument

Create a bank account payment instrument for your sub-entity. You can use this payment instrument as a payout destination.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
id
required
string

The sub-entity's ID.

Example: ent_w4jelhppmfiufdnatam37wrfc4
Request Body schema: application/json
required

A JSON payload containing the payment instrument details.

label
required
string (Label) [ 1 .. 50 ] characters

A reference that you can use to identify the payment instrument

type
required
string (Type)

The instrument type

currency
required
string <ISO 4217> (Currency) = 3 characters

The account's currency, as a 3-letter ISO currency code

required
object

Details of the payment instrument being created

Responses
201

Created

400

Bad Request

401

Unauthorized

422

Invalid data was sent

post/accounts/entities/{id}/payment-instruments
Request samples
application/json
{
  • "label": "Bob's Bank Account",
  • "type": "bank_account",
  • "currency": "GBP",
  • "country": "GB",
  • "instrument_details": {
    },
  • "document": {
    }
}
Response samples
application/json
{
  • "id": "ppi_qn4nis4k3ykpzzu7cvtuvhqqga"
}

Query payment instruments

Fetch all of the payment instruments for a sub-entity. You can filter by status to identify verified instruments that are ready to be used for Payouts.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
id
required
string

The sub-entity's ID.

Example: ent_w4jelhppmfiufdnatam37wrfc4
query Parameters
status
string (Status)

The status of your sub-entity's payment instrument. The status indicates the instrument's stage of verification, and whether it can be used for payouts.

Enum: "pending" "verified" "unverified"
Example: status=verified
Responses
200

OK

400

Bad Request

401

Unauthorized

get/accounts/entities/{id}/payment-instruments
Request samples
// For more information please refer to https://github.com/checkout/checkout-sdk-go
import (
	"github.com/checkout/checkout-sdk-go"
	"github.com/checkout/checkout-sdk-go/accounts"
	"github.com/checkout/checkout-sdk-go/configuration"
)

// API Keys
api, err := checkout.
	Builder().
	StaticKeys().
	WithSecretKey("secret_key").
	WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
                        WithEnvironmentSubdomain("{prefix}"). // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
	Build()
if err != nil {
	return nil, err
}

// OAuth
api, err := checkout.
	Builder().
	OAuth().
	WithClientCredentials("client_id", "client_secret").
	WithScopes([]string{configuration.Accounts}).
	WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
                        WithEnvironmentSubdomain("{prefix}"). // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
	Build()
if err != nil {
	return nil, err
}

query := accounts.PaymentInstrumentsQuery{Status: "pending"}

response, err := api.Accounts.QueryPaymentInstruments("entity_id", query)
if err != nil {
	return nil, err
}

return response, nil
Response samples
application/json
{
  • "data": [
    ]
}