fig-financial-payments-b2b-xapi

1.0.x
(0 reviews)

Overview

The fig-financial-payments-b2b-xapi enables external B2B partners to initiate and monitor MB WAY payment intents in a secure and traceable manner.

Key Capabilities

  • Create a new MB WAY payment intent (POST /intents/mbway), receiving a unique id.
  • Query the current status of an existing intent (GET /intents/{id}/status).

Communication

This section describes how to interact with the API, including authentication, idempotency, and request/response conventions.

Security
  • All requests must use the HTTPS protocol.
  • Authentication is enforced via OAuth 2.0 Client Credentials flow.

To access the API:

  1. Obtain an access token by calling the Authorization Server with your client_id and client_secret.
  2. Include the token in every request using the Authorization header.

Example: Authorization: Bearer

Additionally, this API enforces idempotency through the Idempotency-Key request header, which must be a unique UUID v4 per payment creation request.

SLA Tiers

The Standard SLA tier allows you to perform up to X requests per minute on the resources of this API.

If your needs exceed these limits, please contact Fidelidade to negotiate access to a higher SLA tier.

Error Handling

Successful requests to the API will return a 2xx status code.

When an error occurs, the API will respond with a status code in the 4xx or 5xx group, enforcing the standard HTTP status codes.

As for the error structure, the API uses a standard structure, that contains the details of the error itself.

Consumers can use the details present in this standard structure to help troubleshoot errors.

In particular, the correlationId can be used by Fidelidade to internally identify the request chain that caused the error.

The following is an example of said structure:

{
  "errorCode": 500,
  "correlationId": "8a9cd990-4888-11ec-8f20-005056b5e555",
  "timeStamp": "2021-11-18T15:59:42Z",
  "description": "The description of the error",
  "detailedDescription": "Further details of the error",
  "externalError": ""
}

Rate Limiting

This API enforces rate limiting at the gateway. When the limit is exceeded, the request is rejected with HTTP 429 – Too Many Requests.

Client guidance

  • Implement retry with exponential backoff (e.g., 1s, 2s, 4s, max 30s) and optional jitter.
  • Avoid aggressive polling on GET /intents/{merchantId}/status. Suggested cadence: start with 2–3s, then back off.
  • Do not parallelize retries for the same resource (merchantId) to prevent thundering herd.

Example 429 response (body follows standard error format)

{
  "errorCode": 429,
  "correlationId": "b8c6d0c0-81c1-11f0-9c0a-005056b539d8",
  "timeStamp": "2025-08-25T15:01:23Z",
  "description": "Too Many Requests",
  "detailedDescription": "Rate limit exceeded. Please retry later using exponential backoff.",
  "externalError": ""
}

Reviews