Status

RECOMMENDATION

We highly recommend using webhooks instead of long-polling to get the status.

Request

To identify the order's status, you can make the following API call:

{
  # A unique id on the merchant side
  "merchantOrderId": "1697637323"
}

Response

{
  "data": {
    # An identifier of the order on our side
    "id": "e300df2c-5692-4efd-8c3b-b1f498709a01",

    # A unique id on the merchant side
    "merchantOrderId": "1697637323",

    # Type of order
    "type": "payout",

    # Time of order creation
    "createdAt": "2023-10-18T12:56:39+00:00",

    # Status of order
    "status": "processing",

    # Sub status of order,
    "subStatus": null,

    # Depends on order type
    # Those fields represent change of balance of merchant wallets
    # Look at order type-specific "Status" sections for more details
    "merchantSourceWallet": null,
    "merchantTargetWallet": null,

    # Transactions that were created during order processing
    # Look at order type-specific "Status" sections for more details
    "transactions": [
      # ...
    ]
  },
  "error": null
}

The response for both Payment and Withdrawal will be similar, but there are some differences in how to interpret it. You can find more details in the order type-specific "Status" sections.

Unexpected errors during order creation

During the order creation phase, you may encounter errors and might be uncertain if the order was created. In this case you need to check that order was actually created or not.

If you receive ORDER_NOT_FOUND error code you should be sure that order was not created.

It is especially vital for withdrawals.

Сабстатус: awaiting_confirmation

Цей сабстатус використовується разом із основним статусом processing. Він означає, що з рахунку відправника вже списані кошти, і ми очікуємо остаточного підтвердження через API перш ніж продовжити обробку платежу. Реагування на сабстатус awaiting_confirmation є опціональним, воно доповнює статус processing.

Якщо транзакція перебуває в статусі processing та сабстатусі awaiting_confirmation більше 20 днів, вона буде автоматично закрита системою.

Webhook

You can also rely on the webhook, which will be sent to the webhookUrl you specified during order creation, once the order receives its final status.

Structure of webhook request will be the same as data object from response of status call.

WARNING

There is no guarantee that the webhook will only be delivered once.

Relies on the so-called at-least-once delivery.

We'll try to deliver webhook until you respond with 200 OK status code. Expected response time must not exceed 3 seconds.

In case of any not expected response or network malfunction, will retry delivery attempt no more than 20 times. Every subsequent webhook retry will be sent with double delay.

Sample

Webhook will have the following structure:

{
   "id": "e300df2c-5692-4efd-8c3b-b1f498709a01",
   "merchantOrderId": "1697637323",
    "type": "payin",
    "createdAt": "2023-10-18T12:56:39+00:00",
    "status": "completed",
    "subStatus": null,
    "merchantSourceWallet": null,
    "merchantTargetWallet": {
        "amount": "100.02",
        "currency": "brl"
    },
    "transactions": [
        # ...
    ]
}

Verification

Webhook verification is essential to confirm that the data received from our server was indeed generated by us and has not been tampered with during transmission.

We rely on the following steps for webhook verification:

Appendix A

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA11FN+8yJrq6X+PD18h8A
x+RrTFxOIiYiuJ0fCFeEOR5mkFhUGuDl6iV8lNsrbOvgePoIz0RrBzx6mVireJJZ
TIp+wa1N3263IqAmAkUpRK+hGi0oxdSUgo0tbUEq64F/pX+5berF0/ZwHp9XpkC1
sNBARPetC74WqSJpiqfqNbH9Ghx/H6qVBW33XE/m49FJbvrbLBWC6ZuWf5RZdQEC
y2NAamQZ9iyoDPuwCCcsMuC5jR0eGSq3mg0p7yKd4UjqEQjniJFkLeE7/UUhk7yr
NDKicqrf7D5I5PprurUJI1LtFvs95vqAxlpekoZ5X9Hf34rxz6+fUIIOYTZSYhmN
QwIDAQAB
-----END PUBLIC KEY-----

Appendix B

18.198.253.217

Appendix C

There are several snippet samples for webhook verification:

openssl dgst -sha512 \
  -verify ./webhook-shared-public-key.pem \
  -signature ./signature \
  ./request-body

POST /webhook-url/1697633610 HTTP/1.1
Host: example.com
Signature: J3xnvxLYUHWVMeIOlUrXl/ljxLLQQmqHB+77SdlO8dh57IFlHM+ne9ir5se/W557Scfp5N8D8BK+SI+8G7TJ4VF3hT4UZeyuD59DUCvP0JhPk3ml5SZ0S/tgW/U82uVqAzlJr1r30/RmJvynRQ9L/SSjYhI0i3UBbKkn5ansslktBPYy5RwBH7LRaoqWwBsIh7TKHpMQ6Jy8OexYW00chtH2NTjeeZzpnzMk0LDrvFgGRRYKpCFUXOGWB51PG5h6dr7qGZ8W9Kl/PAmSQke8VRIj6fwrvIl+B8kCrbm/J6kYgRyRXytgJzJ1hymY908QTYF/PrsLetIHZWvgzO0E3A==


{"data": {}, "error": null}

echo "-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA11FN+8yJrq6X+PD18h8A
x+RrTFxOIiYiuJ0fCFeEOR5mkFhUGuDl6iV8lNsrbOvgePoIz0RrBzx6mVireJJZ
TIp+wa1N3263IqAmAkUpRK+hGi0oxdSUgo0tbUEq64F/pX+5berF0/ZwHp9XpkC1
sNBARPetC74WqSJpiqfqNbH9Ghx/H6qVBW33XE/m49FJbvrbLBWC6ZuWf5RZdQEC
y2NAamQZ9iyoDPuwCCcsMuC5jR0eGSq3mg0p7yKd4UjqEQjniJFkLeE7/UUhk7yr
NDKicqrf7D5I5PprurUJI1LtFvs95vqAxlpekoZ5X9Hf34rxz6+fUIIOYTZSYhmN
QwIDAQAB
-----END PUBLIC KEY-----" > ./webhook-shared-public-key.pem

echo -n '{"data": {}, "error": null}' > ./request-body

echo "J3xnvxLYUHWVMeIOlUrXl/ljxLLQQmqHB+77SdlO8dh57IFlHM+ne9ir5se/W557Scfp5N8D8BK+SI+8G7TJ4VF3hT4UZeyuD59DUCvP0JhPk3ml5SZ0S/tgW/U82uVqAzlJr1r30/RmJvynRQ9L/SSjYhI0i3UBbKkn5ansslktBPYy5RwBH7LRaoqWwBsIh7TKHpMQ6Jy8OexYW00chtH2NTjeeZzpnzMk0LDrvFgGRRYKpCFUXOGWB51PG5h6dr7qGZ8W9Kl/PAmSQke8VRIj6fwrvIl+B8kCrbm/J6kYgRyRXytgJzJ1hymY908QTYF/PrsLetIHZWvgzO0E3A=="|base64 -d > ./signature  

openssl dgst -sha512 \
  -verify ./webhook-shared-public-key.pem \
  -signature ./signature \
  ./request-body

Order status list