Common 🔗

All "paginatable" methods accept parameters:
offset - offset in collection (default - 0)
limit - how many items should be on one page (default - 100)
and return a body like:
{"meta":{"total":12,"limit":100,"offset":0},"data":{"model":[{...},{...}]}}

All API methods should be called with header Content-Type: application/json.

Authorization 🔗

You need to generate API Key first. All requests should contain Authorization header:

curl -X GET|POST|PUT|DELETE ... -H "Authorization: Token XXX"

API v1 🔗

Ping/Pong 🔗

GET https://banking.embily.com/api/v1/ping

Request Example:

curl -X GET 'https://banking.embily.com/api/v1/ping' -H 'Authorization: Token XXX'

200 Success Response:

{
  "ping": "pong"
}

Currencies and Networks 🔗

Account.Currency	Account.Decimals	Account.Kind	Transaction.Network
RUB	2	CHECKING
USD	2	CHECKING
EUR	2	CHECKING \| CARD
USDT	6	CRYPTO	ETH \| TRX
BSC-USD	18	CRYPTO	BSC

Account Information 🔗

GET https://banking.embily.com/api/v1/accounts/:reference

Request Example:

curl https://banking.embily.com/api/v1/accounts/2ff7bfa8-800d-457d-95bf-b9bfcdecc700 \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Token $2a$12$lCQI8ZXsxAOqKDXEq3y1jeKpmgHv/EyXGGL/QUDNDAik4.FxtBsfS'

200 Success Response:

{
  "data": {
    "account": {
      "currency": "USD",
      "reference":"2b18db10-ca57-4af7-8158-1a672bd0afbf",
      "created_at":"2022-03-30T19:12:29.469Z",
      "balance": 200,
      "balance_d": "2.0",
      "decimals": 2,
      "kind": "CHECKING",
      "name": "CHECKING USD"
    }
  }
}

Create Deposit Address 🔗

POST https://banking.embily.com/api/v1/accounts/:account_reference/addresses

Request Example:

curl https://banking.embily.com/api/v1/accounts/2ff7bfa8-800d-457d-95bf-b9bfcdecc700/addresses \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Token $2a$12$lCQI8ZXsxAOqKDXEq3y1jeKpmgHv/EyXGGL/QUDNDAik4.FxtBsfS' \
     -d '{"network":"TRX"}'

200 Success Response:

{
  "data": {
    "address": "TAMYeh5BTMjYSN1bpbB6V1y71PhcHgRaN8"
  }
}

400 Error Response:

{
  "data": {},
  "errors": {
    "network": ["invalid"]
  }
}

Create Transaction 🔗

POST https://banking.embily.com/api/v1/accounts/:account_reference/transactions

Request Example:

curl https://banking.embily.com/api/v1/accounts/2ff7bfa8-800d-457d-95bf-b9bfcdecc700/transactions \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Token $2a$12$lCQI8ZXsxAOqKDXEq3y1jeKpmgHv/EyXGGL/QUDNDAik4.FxtBsfS' \
     -d '{"corr_reference":"5555555555554444","corr_email":"[email protected]","corr_name":"ALEX POPOV","amount":100000}'

Request Example (decimal amount):

curl https://banking.embily.com/api/v1/accounts/2ff7bfa8-800d-457d-95bf-b9bfcdecc700/transactions \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Token $2a$12$lCQI8ZXsxAOqKDXEq3y1jeKpmgHv/EyXGGL/QUDNDAik4.FxtBsfS' \
     -d '{"corr_reference":"5555555555554444","corr_email":"[email protected]","corr_name":"ALEX POPOV","amount_d":"1000.00"}'

"amount_d" is a decimal representation of sending amount regardless the precision of the account's currency the transaction is being created for.

Optional Parameters:

"description" is an optional parameter customer may use for any purpose

200 Success Response:

{
  "data": {
    "transaction": {
      "amount": -100000,
      "currency": "RUB",
      "executed_at": null,
      "reference": "6f552678-3cc0-40cf-931e-d6c7dd5f80be",
      "status": "NEW",
      "created_at": "2022-03-31T00:40:34.589Z",
      "corr_reference": "5555555555554444",
      "corr_email": "[email protected]",
      "corr_name": "ALEX POPOV",
      "amount_d": "-1000.0",
      "description": "Custom String"
    }
  }
}

Create Crypto Transaction 🔗

POST https://banking.embily.com/api/v1/accounts/:account_reference/transactions

Request Example:

curl https://banking.embily.com/api/v1/accounts/2ff7bfa8-800d-457d-95bf-b9bfcdecc700/transactions \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Token $2a$12$lCQI8ZXsxAOqKDXEq3y1jeKpmgHv/EyXGGL/QUDNDAik4.FxtBsfS' \
     -d '{"corr_reference":"TEoEHmutD6d7jrtPThkKu1YyxPYVv697nS","corr_network":"TRX","corr_email":"[email protected]","corr_name":"ALEX POPOV","amount":100000000}'

Note amount is integer and for USDT decimal value is 6, refer to currencies description

200 Success Response:

{
  "data": {
    "transaction": {
      "amount": -100000000,
      "currency": "USDT",
      "executed_at": null,
      "reference": "6f552678-3cc0-40cf-931e-d6c7dd5f80be",
      "status": "NEW",
      "created_at": "2022-03-31T00:40:34.589Z",
      "corr_reference": "TEoEHmutD6d7jrtPThkKu1YyxPYVv697nS",
      "corr_network": "TRX",
      "corr_email": "[email protected]",
      "corr_name": "ALEX POPOV",
      "amount_d": "-100.000000"
    }
  }
}

Cancel Transaction 🔗

DELETE https://banking.embily.com/api/v1/transactions/:transaction_reference

Request Example:

curl -X DELETE https://banking.embily.com/api/v1/transactions/27ff6a65-12ed-461c-954e-f200c6ef2fc7 \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Token $2a$12$lCQI8ZXsxAOqKDXEq3y1jeKpmgHv/EyXGGL/QUDNDAik4.FxtBsfS'

200 Success Response:

{
  "data": {
    "transaction": {
      "status": "CANCEL",
      "currency": "RUB",
      "reference": "27ff6a65-12ed-461c-954e-f200c6ef2fc7",
      "corr_reference": "5555555555554444",
      "amount": -100000,
      "executed_at": null,
      "created_at": "2022-03-31T00:47:54.434Z",
      "corr_email": "[email protected]",
      "corr_name": "ALEX POPOV",
      "amount_d": "-1000.0"
    }
  }
}

Show Transaction 🔗

GET https://banking.embily.com/api/v1/transactions/:transaction_reference

Request Example:

curl https://banking.embily.com/api/v1/transactions/27ff6a65-12ed-461c-954e-f200c6ef2fc7 \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Token $2a$12$lCQI8ZXsxAOqKDXEq3y1jeKpmgHv/EyXGGL/QUDNDAik4.FxtBsfS'

200 Success Response:

{
  "data": {
    "transaction": {
      "status": "CANCEL",
      "currency": "RUB",
      "reference": "27ff6a65-12ed-461c-954e-f200c6ef2fc7",
      "corr_reference": "5555555555554444",
      "amount": -100000,
      "executed_at": null,
      "created_at": "2022-03-31T00:47:54.434Z",
      "corr_email": "[email protected]",
      "corr_name": "ALEX POPOV",
      "amount_d": "-1000.0"
    }
  }
}

List Transactions 🔗

GET https://banking.embily.com/api/v1/accounts/:account_reference/transactions

Request Example:

curl "https://banking.embily.com/api/v1/accounts/2ff7bfa8-800d-457d-95bf-b9bfcdecc700/transactions?limit=5&offset=2" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Token $2a$12$lCQI8ZXsxAOqKDXEq3y1jeKpmgHv/EyXGGL/QUDNDAik4.FxtBsfS'

200 Success Response:

{
  "meta": {
    "total": 29,
    "limit": 5,
    "offset": 2
  },
  "data": {
    "transactions": [
      {
        "amount": -100000,
        "currency": "RUB",
        "executed_at": null,
        "reference": "abd19dac-11ad-498c-b352-f3315de64f8d",
        "status": "NEW",
        "created_at": "2022-03-31T00:46:38.175Z",
        "corr_reference": "5555555555554444",
        "corr_email": "[email protected]",
        "corr_name":"ALEX POPOV",
        "amount_d": "-1000.0"
      },
      {
        "amount": -100000,
        "currency": "RUB",
        "executed_at": null,
        "reference": "498e377c-c569-4202-a852-c5106b755cc0",
        "status": "NEW",
        "created_at": "2022-03-31T00:46:18.065Z",
        "corr_reference": "5555555555554444",
        "corr_email": "[email protected]",
        "corr_name": "ALEX POPOV",
        "amount_d": "-1000.0"
      },
      ...
    ]
  }
}

API v2 🔗

Response format:

{"code":"STATUS_CODE","data":{},"message":"Helper message!"}

Status Codes 🔗

Applicable for /api/v2/ methods only

SUC0000 (HTTP 200) - Success

ERR0009 (HTTP 404) - Item not found

ERR0999 (HTTP 500) - Server error

ERR6001 (HTTP 500) - External processing error

ERR6002 (HTTP 500) - Non acceptable payment method

ERR0099 (HTTP 400) - Missing params or body

ERR0100 (HTTP 400) - Incorrect swap information

ERR0000 (HTTP 403) - Empty headers

ERR0001 (HTTP 403) - Missing "Authorization" header

ERR0002 (HTTP 403) - Malformed "Authorization" headers

ERR0003 (HTTP 403) - Wrong authentication type

ERR0004 (HTTP 403) - Inconsistent API key permissions or key not found

ERR0005 (HTTP 400) - User deactivated

ERR0006 (HTTP 400) - Idempotency key (X-I header) is missing

ERR0007 (HTTP 400) - Signature (X-S header) is missing

ERR0008 (HTTP 400) - Wrong signature

Signed requests 🔗

For further protection, you have to sign requests by passing headers:

X-I - idempotency key, unique for each request, for example timestamp

X-S - signature using the following formula:

HEX_SHA256(idem + api_token + request.fullpath + request.raw_post)

If signature doesn't match, 403 (unauthorized code) will be returned

curl -X GET|POST ... -H "X-S: SIGNATURE" -H "X-I: UNIQUE_TOKEN" -H "Authorization: Token TOKEN"

Let's assume you're sending GET request to /api/v2/time, using api key -_F2VMPJX9M79QIBR5EBDEJND-EYWPZCDYYNVQCB-UGX_69IR3FXY2RMBXZYZ8TM and nonce 1666132194844

The signing string is:

1666132194844-_F2VMPJX9M79QIBR5EBDEJND-EYWPZCDYYNVQCB-UGX_69IR3FXY2RMBXZYZ8TM/api/v2/time

The signature is:

69ba55f36e092a86b3eec0daf3be76352244797d44ee45c7e4b0eae5689ac3c8

If you're sending GET request with query params like /api/v2/time?q=1

The signing string is:

1666132194844-_F2VMPJX9M79QIBR5EBDEJND-EYWPZCDYYNVQCB-UGX_69IR3FXY2RMBXZYZ8TM/api/v2/time?q=1

The signature is:

3d456e944ce0be03d05e3da8f3dff8864c84da45c4a597abe03341b629d45a7a

If you're sending POST request to /api/v2/some/endpoint with body {"param":"value"}

The signing string is:

1666132194844-_F2VMPJX9M79QIBR5EBDEJND-EYWPZCDYYNVQCB-UGX_69IR3FXY2RMBXZYZ8TM/api/v2/some/endpoint{"param":"value"}

The signature is:

e0bec05a15eac77808297b9189c7b3cd300f79fe8f013cb5f9167b9c49528527

Server Time 🔗

GET https://banking.embily.com/api/v2/time

Request Example:

curl "https://banking.embily.com/api/v2/time" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Token $2a$12$lCQI8ZXsxAOqKDXEq3y1jeKpmgHv/EyXGGL/QUDNDAik4.FxtBsfS'

200 Success Response:

{
  "code": "SUC0000",
  "data": {
    "time": "1666134807223"
  },
  "message": ""
}

Create Swap Payment 🔗

POST https://banking.embily.com/api/v2/swaps

Request Example:

curl "https://banking.embily.com/api/v2/swaps" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Token $2a$12$lCQI8ZXsxAOqKDXEq3y1jeKpmgHv/EyXGGL/QUDNDAik4.FxtBsfS' \
     -d '{...}'

Body:

{
  "swap":
  {
      "topup_debit_account_provider": "NUVEI",
      "debit_currency": "EUR",
      "credit_currency": "EURX",
      "fixed_entry": "DEBIT",
      "debit_amount": "40000",
      "redirect_url": "https://example.com/order/5715"
  },
  "card":
  {
      "number": "2221008123677736",
      "holder": "CL-BRW2",
      "year": "25",
      "month": "06",
      "cvv": "007"
  },
  "billing":
  {
      "country": "EE",
      "city": "Tallinn",
      "address": "Bryanskaya 4, 25",
      "zip": "121059",
      "email": "[email protected]",
      "first_name": "Evgeny",
      "last_name": "khashin"
  },
  "device":
  {
      "accept_header": "application/json",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36",
      "language": "EN",
      "screen_height": "758",
      "screen_width": "1280",
      "time_zone": 3,
      "ip": "202.122.33.1"
  }
}

topup_debit_account_provider possible values

NUVEI - default value, used for VISA and MC

WLT - for MC cards only

Swap Statuses

NEW, CANCEL, INVOICE_PAID, SETTLED

Invoice Statuses

NEW, SUCCESS, FAIL, CANCEL

Payment Intention Statuses

NEW, SUCCESS, FAIL, THREED

200 Success Response:

{
  "code": "SUC0000",
  "data":
  {
      "swap":
      {
          "debit_currency": "EUR",
          "credit_currency": "EURX",
          "debit_amount": 40000,
          "credit_amount": 39200,
          "fixed_entry": "DEBIT",
          "status": "NEW",
          "rate": "1.0",
          "redirect_url": "https://example.com/order/5715"
      },
      "invoice":
      {
          "uuid": "91044190-b96d-43d1-b892-9359bfaf2f94",
          "created_at": "2022-10-19T11:39:48.973Z",
          "currency": "EUR",
          "amount": 40000,
          "status": "NEW",
          "fee_percent": 150,
          "fee_flat": 200,
          "rolling_reserve_percent": 200,
          "processing_error": null
      },
      "payment_intention":
      {
          "uuid": "401bb40e-51fa-447b-a704-2fdc1692d366",
          "created_at": "2022-10-19T11:39:49.006Z",
          "device":
          {
              "ip": "202.122.33.1",
              "accept_header": "application/json",
              "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36",
              "java_enabled": "TRUE",
              "javascript_enabled": "TRUE",
              "language": "EN",
              "screen_height": "758",
              "screen_width": "1280",
              "time_zone": 3
          },
          "billing":
          {
              "country": "EE",
              "city": "Tallinn",
              "address": "Bryanskaya 4, 25",
              "zip": "121059",
              "email": "[email protected]",
              "first_name": "Evgeny",
              "last_name": "khashin"
          },
          "status": "THREED",
          "threed_url": "https://banking.embily.com/swap/pi/401bb40e-51fa-447b-a704-2fdc1692d366/threed"
      }
  },
  "message": ""
}

400 Error Response:

{
  "code": "ERR0099",
  "data": {
    "swap": "required"
  },
  "message": ""
}

400 Error Response:

{
  "code": "ERR0099",
  "data": {
    "swap": {
      "debit_currency": "required",
      "credit_currency":"required",
      "debit_amount": "required"
    }
  },
  "message": ""
}

400 Error Response:

{
  "code": "ERR0100",
  "data": {
    "swap": {
      "withdraw_credit_account_provider": [
        "unsupported"
      ]
    }
  },
  "message": ""
}

500 Error Response:

{
  "code": "ERR0999",
  "data": {},
  "message": "Missing Rate: EUR/HKD"
}

Emulate Swap Payment 🔗

POST https://banking.embily.com/api/v2/swaps

Request Example:

curl "https://banking.embily.com/api/v2/swaps" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Token $2a$12$lCQI8ZXsxAOqKDXEq3y1jeKpmgHv/EyXGGL/QUDNDAik4.FxtBsfS' \
     -d '{...}'

Body:

{
  ... (same fields as in Create Swap method)
  "emulate": true
}

200 Success Response:

{
  "code": "SUC0000",
  "data":
  {
      "swap":
      {
          "debit_currency": "EUR",
          "credit_currency": "EURX",
          "debit_amount": 40000,
          "credit_amount": 39200,
          "fixed_entry": "DEBIT",
          "status": "NEW",
          "rate": "1.0",
          "redirect_url": "https://example.com/order/5715"
      }
  },
  "message": ""
}

400 Error Response:

{
  "code": "ERR0099",
  "data":
  {
      "card":
      {
          "number": "invalid"
      }
  },
  "message": ""
}

400 Error Response:

{
  "code": "ERR0099",
  "data":
  {
      "device":
      {
          "ip": "invalid"
      }
  },
  "message": ""
}

Get Invoice Status 🔗

GET https://banking.embily.com/api/v2/invoices/:uuid

Request Example:

curl "https://banking.embily.com/api/v2/invoices/bed16b56-6f24-458d-be13-f9507fef1841" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Token $2a$12$lCQI8ZXsxAOqKDXEq3y1jeKpmgHv/EyXGGL/QUDNDAik4.FxtBsfS' \

200 Success Response (after create swap):

{
  "code": "SUC0000",
  "data":
  {
      "swap":
      {
          "debit_currency": "EUR",
          "credit_currency": "EURX",
          "debit_amount": 40000,
          "credit_amount": 39200,
          "fixed_entry": "DEBIT",
          "status": "NEW",
          "rate": "1.0",
          "redirect_url": "https://example.com/order/5715"
      },
      "invoice":
      {
          "uuid": "bed16b56-6f24-458d-be13-f9507fef1841",
          "created_at": "2022-10-19T11:39:48.973Z",
          "currency": "EUR",
          "amount": 40000,
          "status": "NEW",
          "fee_percent": 150,
          "fee_flat": 200,
          "rolling_reserve_percent": 200,
          "processing_error": null
      },
      "payment_intentions":
      [
          {
              "uuid": "401bb40e-51fa-447b-a704-2fdc1692d366",
              "created_at": "2022-10-19T11:39:49.006Z",
              "device":
              {
                  "ip": "202.122.33.1",
                  "accept_header": "application/json",
                  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36",
                  "java_enabled": "TRUE",
                  "javascript_enabled": "TRUE",
                  "language": "EN",
                  "screen_height": "758",
                  "screen_width": "1280",
                  "time_zone": 3
              },
              "billing":
              {
                  "country": "EE",
                  "city": "Tallinn",
                  "address": "Bryanskaya 4, 25",
                  "zip": "121059",
                  "email": "[email protected]",
                  "first_name": "Evgeny",
                  "last_name": "khashin"
              },
              "status": "THREED",
              "threed_url": "https://banking.embily.com/swap/pi/401bb40e-51fa-447b-a704-2fdc1692d366/threed"
          }
      ]
  },
  "message": ""
}

200 Success Response (when swap payment failed):

{
  "code": "SUC0000",
  "data":
  {
      "swap":
      {
          "debit_currency": "EUR",
          "credit_currency": "EURX",
          "debit_amount": 40000,
          "credit_amount": 39200,
          "fixed_entry": "DEBIT",
          "status": "NEW",
          "rate": "1.0",
          "redirect_url": "https://example.com/order/5715"
      },
      "invoice":
      {
          "uuid": "bed16b56-6f24-458d-be13-f9507fef1841",
          "created_at": "2022-10-19T11:39:48.973Z",
          "currency": "EUR",
          "amount": 40000,
          "status": "NEW",
          "fee_percent": 150,
          "fee_flat": 200,
          "rolling_reserve_percent": 200,
          "processing_error": null
      },
      "payment_intentions":
      [
          {
              "uuid": "401bb40e-51fa-447b-a704-2fdc1692d366",
              "created_at": "2022-10-19T11:39:49.006Z",
              "device":
              {
                  "ip": "202.122.33.1",
                  "accept_header": "application/json",
                  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36",
                  "java_enabled": "TRUE",
                  "javascript_enabled": "TRUE",
                  "language": "EN",
                  "screen_height": "758",
                  "screen_width": "1280",
                  "time_zone": 3
              },
              "billing":
              {
                  "country": "RU",
                  "address": "Bryanskaya 4, 25",
                  "zip": "121059",
                  "email": "[email protected]",
                  "first_name": "Evgeny",
                  "last_name": "khashin"
              },
              "status": "FAIL",
              "threed_url": "https://banking.embily.com/swap/pi/401bb40e-51fa-447b-a704-2fdc1692d366/threed"
          }
      ]
  },
  "message": ""
}

200 Success Response (when swap payment success):

{
  "code": "SUC0000",
  "data":
  {
      "swap":
      {
          "debit_currency": "EUR",
          "credit_currency": "EURX",
          "debit_amount": 40000,
          "credit_amount": 39200,
          "fixed_entry": "DEBIT",
          "status": "SETTLED",
          "rate": "1.0",
          "redirect_url": "https://example.com/order/5715"
      },
      "invoice":
      {
          "uuid": "bed16b56-6f24-458d-be13-f9507fef1841",
          "created_at": "2022-10-19T11:50:29.868Z",
          "currency": "EUR",
          "amount": 40000,
          "status": "SUCCESS",
          "fee_percent": 150,
          "fee_flat": 200,
          "rolling_reserve_percent": 200,
          "processing_error": null
      },
      "payment_intentions":
      [
          {
              "uuid": "9f616654-9f3f-4d7a-8dfc-2273adcabd51",
              "created_at": "2022-10-19T11:50:29.880Z",
              "device":
              {
                  "ip": "202.122.33.1",
                  "accept_header": "application/json",
                  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36",
                  "java_enabled": "TRUE",
                  "javascript_enabled": "TRUE",
                  "language": "EN",
                  "screen_height": "758",
                  "screen_width": "1280",
                  "time_zone": 3
              },
              "billing":
              {
                  "country": "RU",
                  "address": "Bryanskaya 4, 25",
                  "zip": "121059",
                  "email": "[email protected]",
                  "first_name": "Evgeny",
                  "last_name": "khashin"
              },
              "status": "SUCCESS",
              "threed_url": "https://banking.embily.com/swap/pi/9f616654-9f3f-4d7a-8dfc-2273adcabd51/threed"
          }
      ]
  },
  "message": ""
}

Create Invoice 🔗

POST https://banking.embily.com/api/v2/swaps/invoices

Used to create an invoice, customer processes payment on Embily's payment page.

Request Example:

curl "https://banking.embily.com/api/v2/swaps/invoices" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Token $2a$12$lCQI8ZXsxAOqKDXEq3y1jeKpmgHv/EyXGGL/QUDNDAik4.FxtBsfS' \
     -d '{...}'

Example of body with required fields only:

This is the case we ask customer to confirm his email address and enter personal information step by step.

{
  "swap": {
    "debit_currency": "EUR",
    "credit_currency": "EURX",
    "debit_amount": "10000",
    "redirect_url": "https://google.com",
  }
}

Full list of possible fields:

This is the case we do not ask customer to enter anything except card details to complete the payment.

{
  "swap": {
    "debit_currency": "EUR",
    "credit_currency": "EURX",
    "debit_amount": "10000",
    "redirect_url": "https://google.com"
  },
  "billing": {
    "email": "[email protected]",
    "address": "1321 N.Poinsettia Pl., 12",
    "city": "Los Angeles",
    "zip": "90046",
    "country": "US",
    "first_name": "Eugene",
    "last_name": "Khashin"
  }
}

Response example:

You need to redirect customer to pay_redirect_url and we will redirect customer back to your endpoint once 3DS is passed.

{
  "code": "SUC0000",
  "data": {
    "swap": {
      "debit_currency": "EUR",
      "credit_currency": "EURX",
      "debit_amount": 10000,
      "credit_amount": 9650,
      "fixed_entry": "DEBIT",
      "status": "NEW",
      "rate": "1.0",
      "redirect_url": "https://google.com"
    },
    "invoice": {
      "uuid": "4736e008-54b2-494a-a7c8-52878b3d824e",
      "created_at": "2023-03-10T18:33:50.476Z",
      "currency": "EUR",
      "amount": 10000,
      "status": "NEW",
      "fee_percent": 150,
      "fee_flat": 200,
      "rolling_reserve_percent": 0,
      "processing_error": null,
      "billing": {
        "country": "US",
        "city": "Los Angeles",
        "address": "1321 N.Poinsettia Pl., 12",
        "zip": "90046",
        "email": "[email protected]",
        "first_name": "Evgeny",
        "last_name": "Khashin"
      },
      "pay_redirect_url": "http://pay.embily.com/#/i/4736e008-54b2-494a-a7c8-52878b3d824e"
    }
  },
  "message": ""
}

Webhooks 🔗

We can make HTTP POST requests to your backend once events on our end are fired.

You can create multiple webhook URLs on page https://banking.embily.com/webhooks

Event webhook body structure:

{
  "data": {
    "event": {
      "time": TIMESTAMP,
      "models": MODELS_NAMES_ARRAY
    },
    MODEL_1_NAME: MODEL_1_BODY_OBJECT,
    MODEL_2_NAME: MODEL_2_BODY_OBJECT,
    MODEL_3_NAME_PLURAL: MODEL_3_BODIES_ARRAY,
    ...
  }
}

TIMESTAMP is event timestamp in milliseconds, for example: 1670687494186

MODELS_NAMES_ARRAY is an array of models are changed, for example ["transaction"]

MODEL_{N}_NAME is an object of each model changed or related to any of changed models in array (examples described below). Note for some models you might find plural names and array instead of objects (look examples below).

Important: events order is defined and TIMESTAMPs are generated according to the exact time events are fired, but we can't guarantee your server gets events the same order we send it to you, because there might be communication issues we do not control. In this case we strictly recommend you to use one of techniques:

1. Do not process webhooks with timestamps which are lower in comparison to the latest processed event timestamp.

2. Do not rely on body content and process synchronous request to server once you have received webhook, getting just related models UUIDs to make new GET requests to server.

Event webhook headers:

Name	Value	Description
Content-Type	application/json	JSON content type
User-Agent	EmbilyProxy/{VERSION}	Version of our software, current version is 1.0.1
X-S	{HEX_SIGNATURE}	prime256v1 ecdsa signature of SHA-256 of request body (described below)

Signature 🔗

Type	ECDSA
Curve	prime256v1 (possible aliases: secp256r1, NIST P-256)
Hashing function	SHA-256
Format	DER ASN.1, OpenSSL compatible

Our public key you need to use to validate signature in uncompressed form:

0438949c137646efd3f7b3b8645dd75c078071ac76bf2c3e0a35e53952b49229b3801e4f438f8b31d04397a3af88903bc0ca3a950c7e51481a3403738173aae3d5

Body example (should be presented as a string variable, we sign request body as-is):

{"message":"hello world"}

SHA-256 of body:

f96d8d3757ef3216aaf9778e048aaaf0803c8fb2c95ea2fc65c482d6b8433015

Example of signature:

3045022100bae2d66a9fa0a7fac7d8912a406d99fa588c2f24185cf7cf07229fb454b8b75d022071b241f866dcdb847d8791d297b15f43a51162c3526cc2ffb2b647d59ef99527

You can validate it manually using some external tools like https://kjur.github.io/jsrsasign/sample/sample-ecdsa.html, using secp256r1 as a curve, filling just private key, message, and signature:

Retry Rules 🔗

We retry all requests to your server, please contact your manager to disable this feature if you need to.

We retry failures (non-2xx codes) with an exponential backoff using the formula (retry_count ** 4) + 15 + (rand(30) * (retry_count + 1)) seconds (i.e. 15, 16, 31, 96, 271, ... seconds + a random amount of time). It will perform 25 retries over approximately 21 days.

Transaction 🔗

Tracking fields: status, approved, blockchain_hash

Body example:

{
  "data": {
    "event": {
      "time": 1670691642710,
      "models": [
        "transaction"
      ]
    },
    "transaction": {
      "amount": -100000,
      "currency": "RUB",
      "executed_at": "2022-12-10T17:00:31.304Z",
      "reference": "4f8baa19-5337-4ec3-a7fa-8a23511fe3b7",
      "description": "",
      "status": "CANCEL",
      "created_at": "2022-12-10T17:00:31.310Z",
      "corr_reference": "5555555555554444",
      "corr_email": "[email protected]",
      "corr_name": "ALEX POPOV",
      "corr_network": null,
      "blockchain_hash": null,
      "approved": false,
      "amount_d": "-1000.0"
    }
  }
}

Body of transaction is the same as you get it using Show Transaction method.

Swap 🔗

Data consists of 3 related models joined in one webhook: swap, invoice, payment_intentions (note, payment_intentions is in plural form as it's an array).

Tracking fields for swap model: status

Tracking fields for invoice model: status

Tracking fields for payment_intentions model: status

Body example:

{
  "data": {
    "event": {
      "time": 1670691357599,
      "models": [
        "swap",
        "invoice",
        "payment_intentions"
      ]
    },
    "swap": {
      "debit_currency": "EUR",
      "credit_currency": "EURX",
      "debit_amount": 40000,
      "credit_amount": 39200,
      "fixed_entry": "DEBIT",
      "status": "NEW",
      "rate": "1.0",
      "redirect_url": "https://example.com/order/5715"
    },
    "invoice": {
      "uuid": "6444d395-6282-473b-9a6d-76cb5897aba8",
      "created_at": "2022-12-10T16:55:46.965Z",
      "currency": "EUR",
      "amount": 40000,
      "status": "NEW",
      "fee_percent": 150,
      "fee_flat": 200,
      "rolling_reserve_percent": 200,
      "processing_error": null
    },
    "payment_intentions": [
      {
        "uuid": "c61a9d5d-b105-4a7d-bdcf-9fa0f0077bf2",
        "created_at": "2022-12-10T16:55:47.010Z",
        "device": {
          "ip": "202.122.33.1",
          "accept_header": "application/json",
          "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36",
          "java_enabled": "TRUE",
          "javascript_enabled": "TRUE",
          "language": "EN",
          "screen_height": "758",
          "screen_width": "1280",
          "time_zone": 3
        },
        "billing": {
          "country": "DE",
          "address": "Br br br 4, 25",
          "zip": "000000",
          "email": "[email protected]",
          "first_name": "Evgeny",
          "last_name": "khashin"
        },
        "status": "THREED",
        "threed_url": "https://banking.embily.com/swap/pi/c61a9d5d-b105-4a7d-bdcf-9fa0f0077bf2/threed"
      }
    ]
  }
}

Body of models is the same as you get it using Get Invoice Status method.