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 the LaFinteca 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",

    # 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.

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.

LaFinteca 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, LaFinteca 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",
    "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-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu5hLf3cJmFvtzPbQ+Ipc
A6AdxVq0nJNAkiHj6LbADiTm8ByrBsXfYp1kcTBU0LQEf1eZCpacOLDLqcHkChSw
VAng1SumYIW5YBPOBSOziifaJO5/Ecp0fVhZJ1aApAZbuw5JvAVZ36BHOr30Dp2F
Pru6R8w+7p2mG5FCCpjAfl4VQyDAlz0PzNwm11nHenvNcZq6Xq3W33/fG8lWEmt3
sPAeotNxClOSyx/dPldiHpnwPqXhTdXHCHhGJJbtuaSjSDFIig0W7KfwbVC7uCsN
e1IBR4wGSiTcVTNWkyBc7TXnp7rUErv6JHsTVEXbTgYZNP86fP4OD50UI/G3maPF
CQIDAQAB
-----END PUBLIC KEY-----

Appendix B

54.232.47.110

Appendix C

There are several snippet samples for webhook verification:

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