Account Chaining BETA
Topics covered on this page
Account Chaining is a feature allowing you to create charges and perform other actions on behalf of other merchants. This is useful for operating a marketplace or similar platform without having to manually manage other merchants' secret keys.
Chains can be created, listed, and revoked via the dashboard. Chains can be listed and revoked via the API.
How to enable
- Supported Countries: Thailand, Japan, Singapore
- Minimum API version:
2014-07-27
To enable Account Chaining, send an email requesting this feature to support@omise.co. You will need to review and accept new terms and conditions.
Terms
- Merchant
- Seller acting the on behalf of sub-merchant. Usually, the operator of a marketplace.
- Sub-merchant
- Seller on whose behalf merchant performs actions. Usually, a seller within a marketplace. The sub-merchant must have an Omise account registered within the same country. A single merchant can have many sub-merchants, and vice-versa.
- Chain
- The relationship between the merchant account and the sub-merchant account.
In a principal-agent terms, the sub-merchant can be considered to be the principal while the merchant can be consider to be the agent.
Implementation
Creating a charge on behalf of a sub-merchant is similar to creating a normal charge.
Instead of using your secret key to authenticate the POST request to the charge endpoint, you use the chain key specific to the sub-merchant.
The steps for creating a charge on behalf of a sub-merchant are as follows:
- Create a token using your merchant public key
- Create a charge using the sub-merchant's chain key
For chained charges, the sub-merchant's own secret and public keys are not used
Creating a token
Create a token using your public key.
curl https://vault.omise.co/tokens \
-X POST \
-u $OMISE_PUBLIC_KEY: \
-d "card[name]=Somchai Prasert" \
-d "card[city]=Bangkok" \
-d "card[postal_code]=10320" \
-d "card[number]=4242424242424242" \
-d "card[security_code]=123" \
-d "card[expiration_month]=12" \
-d "card[expiration_year]=2022"
{
"object": "token",
"id": "tokn_test_5kkfa72s2ts6t93tpcl",
"livemode": false,
"location": "https://vault.omise.co/tokens/tokn_test_5kkfa72s2ts6t93tpcl",
"used": false,
"charge_status": "unknown",
"card": {
"object": "card",
"id": "card_test_5kkfa72rkk722waynij",
"livemode": false,
"location": null,
"deleted": false,
"street1": null,
"street2": null,
"city": "Bangkok",
"state": null,
"phone_number": null,
"postal_code": "10320",
"country": "gb",
"financing": "credit",
"bank": "SAMPLE BANK",
"brand": "Visa",
"fingerprint": "XjOdjaoHRvUGRfmZacMPcJtm0U3SEIIfkA7534dQeVw=",
"first_digits": null,
"last_digits": "4242",
"name": "Somchai Prasert",
"expiration_month": 12,
"expiration_year": 2022,
"security_code_check": true,
"created_at": "2020-07-17T07:41:48Z"
},
"created_at": "2020-07-17T07:41:48Z"
}
Creating a charge
First, follow these instructions to enable account chaining and add new sub-merchants. You will find a list of sub-merchants and their chain keys on the dashboard.
You may also list sub-merchants on your account using the chains endpoint.
Find the sub-merchant chain key on the key attribute; chain keys begin with the string ckey.
curl https://api.omise.co/chains \
-u $OMISE_SECRET_KEY:
{
"object": "list",
"data": [
{
"object": "chain",
"id": "acch_test_5fo0sjwiczl3bc4jxk1",
"livemode": false,
"location": "/chains/acch_test_5fo0sjwiczl3bc4jxk1",
"revoked": true,
"email": "somchai.prasert@esimo.co",
"key": "",
"created_at": "2019-04-23T07:34:46Z"
},
{
"object": "chain",
"id": "acch_test_5fo0vzjg760u8gl4oma",
"livemode": false,
"location": "/chains/acch_test_5fo0vzjg760u8gl4oma",
"revoked": false,
"email": "somchai.prasert@esimo.co",
"key": "ckey_test_5fo0z33p6lqwef0xjl5",
"created_at": "2019-04-23T07:44:31Z"
}
],
"limit": 20,
"offset": 0,
"total": 2,
"location": null,
"order": "chronological",
"from": "1970-01-01T00:00:00Z",
"to": "2020-07-17T07:41:49Z"
}
Create a charge using the token identifier from above and the sub-merchant's chain key.
curl https://api.omise.co/charges \
-X POST \
-u $OMISE_CHAIN_KEY: \
-d "amount=10000" \
-d "currency=THB" \
-d "card=$TOKEN_ID"
Voids and refunds
Create refunds using the chain key.
curl https://api.omise.co/charges/$CHARGE_ID/refunds \
-u $OMISE_CHAIN_KEY: \
-d "amount=10000"
{
"object": "refund",
"id": "rfnd_test_5kkfa7fl3i3r2jzywul",
"location": "/charges/chrg_test_5kkfa6l05nqemf3qsvd/refunds/rfnd_test_5kkfa7fl3i3r2jzywul",
"livemode": false,
"voided": false,
"currency": "THB",
"amount": 10000,
"metadata": {},
"charge": "chrg_test_5kkfa6l05nqemf3qsvd",
"terminal": null,
"transaction": "trxn_test_5kkfa7foxbg4lccik0l",
"status": "closed",
"funding_amount": 10000,
"funding_currency": "THB",
"created_at": "2020-07-17T07:41:50Z"
}
Creating a transfer
Create a transfer using the sub-merchant's chain key.
curl https://api.omise.co/transfers \
-X POST \
-u $OMISE_CHAIN_KEY: \
-d "amount=10000"
{
"object": "transfer",
"id": "trsf_test_5kkfa7jjzdthw71xaig",
"livemode": false,
"location": "/transfers/trsf_test_5kkfa7jjzdthw71xaig",
"deleted": false,
"fail_fast": false,
"paid": false,
"sent": false,
"sendable": true,
"currency": "THB",
"amount": 10000,
"fee": 2804,
"metadata": {},
"recipient": "recp_test_5fo1651prcuefm48899",
"bank_account": {
"object": "bank_account",
"livemode": false,
"last_digits": "6789",
"name": "DEFAULT BANK ACCOUNT",
"type": null,
"created_at": "2019-04-23T08:13:21Z",
"brand": "Test Bank",
"bank_code": "test",
"branch_code": null
},
"failure_code": null,
"failure_message": null,
"paid_at": null,
"sent_at": null,
"created_at": "2020-07-17T07:41:50Z",
"transactions": [],
"schedule": null,
"fee_vat": 196,
"net": 7000,
"total_fee": 3000
}
Events
Both accounts will receive sub-merchant events to their respective Webhook endpoints. Events will have different identifiers.
