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:

  1. Create a token using your merchant public key
  2. 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.

Related

Omise uses cookies to improve your overall site experience and collect information on your visits and browsing behavior. By continuing to browse our website, you agree to our Privacy Policy. Learn more