Manage sub-entity card details
Last updated: July 26, 2023
With a Full account, you have complete access to Checkout.com's payouts capabilities. For example, you can pay out to a sub-entity card. For us to support you with this, you need to securely store the card details information, using a payment instrument.
To create a card payment instrument:
- You must have passed eligibility checks
- The issuer country must be a country supported by Checkout.com’s Integrated Platforms solution
Before you can perform payouts to a sub-entity, you must connect card details to the sub-entity’s account, so we know where to send the funds.
The sub-entity's card details are stored in our Vault as a payment instrument, so that you can reuse it in future payouts without needing to type out the card details every time.
When a sub-entity is created, a Checkout.com currency account is automatically associated with that sub-entity. When you request a payment on behalf of your sub-entity, those funds are routed to their currency account.
With our Payouts solution, you can use the secure payment instrument to ensure those funds are then paid out to the sub-entity's card.
Use Frames to add the recipient's card details and convert them into a token. This will keep you PCI-compliant. You can then use this token to create the payment instrument by calling the following endpoint:
post
https://api.checkout.com/accounts/entities/{id}/payment-instruments
To get a detailed view of all required and optional fields, see our API reference.
Note
Scheduled card payouts are not currently supported.
If your request is successful, the payment instrument will be created and a payment instrument_id returned.
You can use this ID value to retrieve details about the payment instrument.
Once you have created the payment instrument, it will automatically go through a due diligence verification process.
The instrument cannot be used until it has successfully passed the verification process. If you've enabled webhook notifications, you'll be notified of the verification process outcome through a webhook.
You can retrieve a payment instrument's ID using the
get
/accounts/entities/{entityId}/payment-instruments/{id} endpoint.The response's instrument_id value is a unique reference to your instrument's details, which you can use to identify it when using our other APIs. The payment instrument's details are not returned in the response.