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:

POST /api/v3/order/get-status
{
# A unique id on the merchant side
"merchantOrderId": "1697637323"
}

Response

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:

RESPONSE
{
"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:

  1. Shared Public Key: We provide a shared public key that all merchants use to verify webhook requests.
  2. Request Signature: With each webhook payload sent from our server, we include a base64-encoded Signature header that is created by private key using sha512. This signature is unique to each request and ensures that the data has not been altered in transit.
  3. Signature Verification: Upon receiving a webhook request, you should retrieve the included signature and use the shared public key to verify the signature. If the verification is successful, you can be confident that the webhook data is authentic and unaltered.
  4. IP Whitelisting: To further enhance security, it is highly recommended that you maintain a whitelist of IP addresses from which you will accept webhook requests. This ensures that only requests originating from trusted sources are accepted by your application.

Appendix A

 

Shared Public Key
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu5hLf3cJmFvtzPbQ+Ipc
A6AdxVq0nJNAkiHj6LbADiTm8ByrBsXfYp1kcTBU0LQEf1eZCpacOLDLqcHkChSw
VAng1SumYIW5YBPOBSOziifaJO5/Ecp0fVhZJ1aApAZbuw5JvAVZ36BHOr30Dp2F
Pru6R8w+7p2mG5FCCpjAfl4VQyDAlz0PzNwm11nHenvNcZq6Xq3W33/fG8lWEmt3
sPAeotNxClOSyx/dPldiHpnwPqXhTdXHCHhGJJbtuaSjSDFIig0W7KfwbVC7uCsN
e1IBR4wGSiTcVTNWkyBc7TXnp7rUErv6JHsTVEXbTgYZNP86fP4OD50UI/G3maPF
CQIDAQAB
-----END PUBLIC KEY-----

Appendix B

NAT IPs
54.232.47.110

Appendix C

There are several snippet samples for webhook verification:

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

Are there any inquiries still outstanding?

Our team of experts is available 24/7 to answer all your questions. Feel free to reach out to us at any time, and we will be happy to help you address any inquiries or issues. Your comfort and satisfaction are our priority.
Need help?Contact support

Powered by LA FRAMBUESA & Markdoc