Felix-Integrations-API (1.4.0)

Download OpenAPI specification:Download

Introduction

Welcome to Félix's Remittance Requests Management System. Our platform is designed to streamline and simplify managing remittance requests, ensuring efficient and secure transfers for both senders and recipients.

Our Solution

The Félix API offers a comprehensive solution to manage remittance requests effectively. Our platform empowers you to:

  • Create Remittance Requests: Easily initiate remittance requests on behalf of the intended receivers.
  • Monitor Remittance Requests: Keep track of the status and progress of remittance requests in real-time from its creation up to its ramp-off in the receiving country.

Key Features

  • Security: Ensure the security and privacy of financial data with robust encryption.
  • Compliance: Stay compliant with international regulations and anti-money laundering (AML) requirements.
  • Scalability: Adapt to changing business needs and scale your remittance operations easily.
  • Integration: Seamlessly integrate our platform with your existing systems through our API.

Transaction Status Flow

The status of a remittance request changes as it progresses through the system. The status flow is as follows:

  • CREATED: The remittance request is created and waiting for sender start the process.
  • STARTED: The sender has initiated the remittance process.
  • CONFIRMED: The remittance was paid and confirmed by the sender.
  • IN_PROGRESS: The remittance request is in progress.
  • COMPLETED: The remittance request has been successfully completed.
  • FAILED: The remittance request has failed, this can change if an operator manually resolves the issue.
  • CANCELLED: The remittance request has been cancelled.
  • REFUNDED: The remittance request has been refunded.

Remittance Request Status Flow

Callback (Update Notifications)

This callback notification system is designed to optimize efficiency and reliability in the communication of transaction status updates. A key part of this strategy involves the use of "Notification Deltas," which are compact representations of changes in transaction status that have not yet been successfully communicated to the intended recipient.

Advantages of our structured approach include:

  • Reduced Network Load: By aggregating changes into deltas, we significantly decrease the number of requests made across the network.
  • Intelligent Retry Mechanism: We employ an exponential backoff policy for notification retries in case of failure. The waiting time starts at 60 second and doubles with each subsequent retry, max 10 retries.
  • Focused Data Persistence: We currently cache only the deltas of unsent notifications, which significantly reduces the demand on our database resources.
  • Streamlined Notification Process: Packaging failed notifications into deltas allows for efficient reconciliation and re-notification.
  • Operational Flexibility: Our architecture provides the flexibility to adapt our notification strategy as our needs evolve. We have introduced new entities such as TransactionResponse, NotificationDelta, Notification, and NotificationsContainer to support this enhanced system. Examples of the payload we send to your callback illustrate both the "happy path" and more complex paths involving multiple transactions and notifications with multiple deltas.

Note: To further enhance flexibility and efficiency in handling transaction updates, we have designed our system with optional callback functionality. Clients have the opportunity to proactively query transactions with specific statuses, allowing them to retrieve the most up-to-date information.

To ensure seamless integration and maintain consistency, we strongly recommend that clients use the field names as defined in our documentation. This practice is designed to standardize data handling and allow for greater flexibility on the part of our clients.

 TransactionResponse:
      type: object
      properties:
        id:
          type: string
        provider_id:
          type: string
        sender_id:
          type: string
          nullable: true
        name:
          type: string
        middle_name:
          type: string
          nullable: true
        lastname:
          type: string
        second_lastname:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        clabe:
          type: string
        amount:
          type: number
          format: decimal
          default: 0.0
        currency:
          $ref: '#/CurrencyEnum'
        status:
          $ref: '#/TransactionStatusEnum'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          nullable: true
        metafields:
          type: object
          additionalProperties: true
          nullable: true

    NotificationDelta:
      type: object
      properties:
        old_status:
          $ref: '#/TransactionStatusEnum'
        new_status:
          $ref: '#/TransactionStatusEnum'
        updated_at:
          type: string
          format: date-time
          nullable: true

    Notification:
      type: object
      properties:
        transaction:
          $ref: '#/TransactionResponse'
        deltas:
          type: array
          items:
            $ref: '#/NotificationDelta'

    NotificationsContainer:
      type: object
      properties:
        provider_id:
          type: string
        callback_url:
          type: string
        notifications:
          type: array
          items:
            $ref: '#/Notification'

If you have a callback registered, we will send you a POST request with a JSON payload with NotificationContainer as the body. The payload will contain the provider_id, callback_url, and notifications array. The notifications array will contain the transaction object and an array of deltas.

Each notification is associated with a just one transaction, and each notification can have multiple deltas.

Example of payload simple path (just one transaction and one notification with two deltas):

{
    "provider_id": "123456",
    "callback_url": "https://your-callback-url.com",
    "notifications": [
        {
            "transaction": {
                "id": "123456",
                "provider_id": "123456",
                "sender_id": "123456",
                "name": "John",
                "middle_name": "Doe",
                "lastname": "Smith",
                "second_lastname": "Johnson",
                "city": "New York",
                "state": "NY",
                "amount": 100.0,
                "currency": "USD",
                "status": "COMPLETED",
                "created_at": "2021-10-01T12:00:00Z",
                "updated_at": "2021-10-01T12:00:00Z",
                "metafields": {
                    "key1": "value1",
                    "key2": "value2"
                }
            },
            "deltas": [
                {
                    "old_status": "CONFIRMED",
                    "new_status": "IN_PROCESS",
                    "updated_at": "2021-10-01T12:00:00Z"
                },
                {
                    "old_status": "IN_PROCESS",
                    "new_status": "COMPLETED",
                    "updated_at": "2021-10-01T12:00:00Z"
                }
            ]
        }
    ]
}

Example of payload complex path (multiple transactions and notifications with multiple deltas):

{
    "provider_id": "5678",
    "callback_url": "https://example.com/callback",
    "notifications": [
        {
            "transaction": {
                "id": "123456",
                "provider_id": "123456",
                "sender_id": "123456",
                "name": "John",
                "middle_name": "Doe",
                "lastname": "Smith",
                "second_lastname": "Johnson",
                "city": "New York",
                "state": "NY",
                "amount": 100.0,
                "currency": "USD",
                "status": "COMPLETED",
                "created_at": "2021-10-01T12:00:00Z",
                "updated_at": "2021-10-01T12:00:00Z",
                "metafields": {
                    "key1": "value1",
                    "key2": "value2"
                }
            },
            "deltas": [
                {
                    "old_status": "CONFIRMED",
                    "new_status": "IN_PROGRESS",
                    "updated_at": "2024-01-02T00:05:00"
                }
            ]
        },
        {
            "transaction": {
                "id": "654321",
                "provider_id": "123456",
                "sender_id": "123456",
                "name": "John",
                "middle_name": "Doe",
                "lastname": "Smith",
                "second_lastname": "Johnson",
                "city": "New York",
                "state": "NY",
                "amount": 100.0,
                "currency": "MXN",
                "status": "COMPLETED",
                "created_at": "2021-10-01T12:00:00Z",
                "updated_at": "2021-10-01T12:00:00Z",
                "metafields": {
                    "key1": "value1",
                    "key2": "value2"
                }
            },
            "deltas": [
                {
                    "old_status": "IN_PROGRESS",
                    "new_status": "FAILED",
                    "updated_at": "2024-01-02T00:07:00"
                }
            ]
        },
        {
            "transaction": {
                "id": "abcdefgh",
                "provider_id": "123456",
                "sender_id": "123456",
                "name": "John",
                "middle_name": "Doe",
                "lastname": "Smith",
                "second_lastname": "Johnson",
                "city": "New York",
                "state": "NY",
                "amount": 100.0,
                "currency": "MXN",
                "status": "COMPLETED",
                "created_at": "2021-10-01T12:00:00Z",
                "updated_at": "2021-10-01T12:00:00Z",
                "metafields": {
                    "key1": "value1",
                    "key2": "value2"
                }
            },
            "deltas": [
                {
                    "old_status": "CREATED",
                    "new_status": "STARTED",
                    "updated_at": "2024-01-02T00:09:00"
                },
                {
                    "old_status": "STARTED",
                    "new_status": "IN_PROGRESS",
                    "updated_at": "2024-01-02T00:10:00"
                }
            ]
        }
    ]
}

FAQ

Can I initiate a transaction without specifying an amount?

Absolutely! If you initiate a transaction without providing an amount or if the amount is set to zero, we will prompt the sender to specify the amount at the beginning of the process.

Getting Started

To get started, you will need to create an account with Félix. Once you have an account, you will be able to get an jwt token to access our API.

Auth

Sign Up

Sign up a new user provider.

Request
Request Body schema: application/json
required
email
required
string <email> (Email)
password
required
string (Password) >= 8 characters
name
required
string (Name)
Responses
201

Successful Response

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

500

Internal Server Error

post/api/v1/signup
Request samples
application/json
{
  • "email": "user@example.com",
  • "password": "stringst",
  • "name": "string"
}
Response samples
application/json
{
  • "id_token": "string",
  • "refresh_token": "string",
  • "expires_in": 0,
  • "id": "string",
  • "email": "string"
}

Sign In

Sign in a user provider.

Request
Request Body schema: application/json
required
email
required
string (Email)
password
required
string (Password)
Responses
200

Successful Response

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

500

Internal Server Error

post/api/v1/signin
Request samples
application/json
{
  • "email": "string",
  • "password": "string"
}
Response samples
application/json
{
  • "id_token": "string",
  • "refresh_token": "string",
  • "expires_in": 0,
  • "id": "string",
  • "email": "string"
}

Providers

Get Provider Me

Get the currently logged in provider.

SecurityJWT
Responses
200

Successful Response

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

500

Internal Server Error

get/api/v1/providers/me
Request samples
Response samples
application/json
{
  • "id": "string",
  • "name": "string",
  • "email": "user@example.com",
  • "headers": {
    },
  • "callback_url": "http://example.com"
}

Register Provider Callback

Register a callback url for the currently logged in provider, this is important for receiving transaction updates.

SecurityJWT
Request
Request Body schema: application/json
required
url
required
string <uri> (Url) [ 1 .. 2083 ] characters
headers
object (Headers)
Responses
200

Successful Response

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

500

Internal Server Error

post/api/v1/providers/callback
Request samples
application/json
{}
Response samples
application/json
null

Transactions

Search Transactions

SecurityJWT
Request
Request Body schema: application/json
required
SearchTransactionFilters (object)
limit
integer (Limit) [ 1 .. 100 ]
Default: 10
offset
integer (Offset) >= 0
Default: 0
Order By (string) (Order By)
Default: "created_at"
Responses
200

Successful Response

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

500

Internal Server Error

post/api/v1/transactions/search
Request samples
application/json
{
  • "filters": {
    },
  • "limit": 10,
  • "offset": 0,
  • "order_by": "created_at"
}
Response samples
application/json
[
  • {
    }
]

Initiate a New Transaction

Initiate a new transaction for the currently logged in provider.

SecurityJWT
Request
Request Body schema: application/json
required
amount
string <decimal>
string
Default: "MXN"
name
required
string
middle_name
string
lastname
required
string
second_lastname
string
city
string
state
string
clabe
required
string
Responses
201

Successfully initiated transaction

400

Bad Request

post/api/v1/transactions
Request samples
application/json
{
  • "amount": "string",
  • "currency": "MXN",
  • "name": "string",
  • "middle_name": "string",
  • "lastname": "string",
  • "second_lastname": "string",
  • "city": "string",
  • "state": "string",
  • "clabe": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "sender_id": "string",
  • "provider_id": "string",
  • "clabe": "string",
  • "amount": "string",
  • "currency": "string",
  • "name": "string",
  • "middle_name": "string",
  • "lastname": "string",
  • "second_lastname": "string",
  • "city": "string",
  • "state": "string",
  • "status": "CREATED",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "metafields": { }
}

Get Transaction Details

Retrieves the details of a specific transaction.

SecurityJWT
Request
path Parameters
transaction_id
required
string <uuid>
Responses
200

Transaction details

400

Bad Request

get/api/v1/transactions/{transaction_id}
Request samples
Response samples
application/json
{
  • "id": "string",
  • "sender_id": "string",
  • "provider_id": "string",
  • "clabe": "string",
  • "amount": "string",
  • "currency": "string",
  • "name": "string",
  • "middle_name": "string",
  • "lastname": "string",
  • "second_lastname": "string",
  • "city": "string",
  • "state": "string",
  • "status": "CREATED",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "metafields": { }
}