Developer Guide
About PayMittoContact Us

Your backend's responsibilities

This guide covers the backend side of a PayMitto SDK integration. Your backend keeps your API credentials, creates the access token and Sender the SDK needs, secures funds, and submits each transfer. Your frontend then launches the PayMitto SDK (Web or native) with the token you create here. Work through the steps in order, and by the end your backend will be ready to support the SDK.

📘

The SDK does the heavy lifting

Recipient and account collection, corridor-specific fields, validation, quotes and exchange rates, disclosures, receipts, and localization all happen in the SDK. Your backend only handles the steps below.

Before you begin

Before you start, make sure you have the following in place:

What you'll do

Here's what you'll do on this page:

  1. Securely store your API credentials.
  2. Authenticate with PayMitto.
  3. Create Sender records for your account holders.
  4. Integrate the PayMitto SDK in your app.
  5. Secure funds for each transfer.
  6. Submit the transfer.

The PayMitto SDK handles the transfer UI and flow. There are three operations that the SDK does not handle: authentication, sender creation, and transfer submission. These are delegated to your backend in order to ensure the security of your users' funds and are the minimum required endpoints to integrate with. For a full list of available PayMitto APIs, see the API Reference.

For where these steps fit in the transfer, see How a PayMitto SDK integration works.

Step 1: Securely store API credentials

PayMitto API credentials will be provided to you by the PayMitto Integrations Team when your integration starts. For more information, see our documentation on Storing API credentials.

Step 2: Authenticate

An access token can be retrieved from the PayMitto API using the Client ID and Client Secret provided to you by the PayMitto Integrations Team when access to a new Environment was granted. It is recommended to get a new OAuth Access Token for each unique intention.

See the documentation on Authentication for more information.

🚧

Access token expiration

Access tokens are long-lived but do expire. The expires_in value in the token response tells you when, so request a new one before it expires.

❗️

Token security

In the wrong hands, the PayMitto API Access Token generated for the P2P use case can be used to see personal information about your users or create fraudulent transfers. Be sure to only store the access token on your backend and never expose it in the frontend.

Step 3: Create Sender records to associate with your user

Sender records represent the entity that owns the funds for the transfer. In the P2P use case, the sender is the individual initiating the Transfer and whose account or value store will be debited when the Transfer is executed.

It is recommended to create a Sender record with the PayMitto API using the Create Sender endpoint when your user attempts to launch the transfer flow for the first time.

📘

Required fields

The fields required to create a Sender with PayMitto are identical across all corridors. Use the Get Sender Fields endpoint to see the full list of required fields. Most information required to create a Sender should already have been collected by your system during user onboarding. The user might need to be prompted for any additional fields (see the guide on Create Senders for tips on this process).

When a Sender record is created successfully, you will be provided a unique senderId. This ID should be saved in your system and associated with the user who initiated the transfer.

🚧

Sender authentication

The access token created in Step 2 is a "Client level" access token, meaning it can be used to view, update, and delete data belonging to any Sender under your customer account. Once a sender exists in the system, it is highly recommended that a "Sender level" access token be used for all other transfer operations through the PayMitto API. For more information on obtaining a Sender level access token, see the guide on Authentication.

Step 4: Integrate PayMitto in your app

The PayMitto SDK provides an end-to-end transfer experience for your users, for domestic and cross-border transfers. Use the Web SDK, a native SDK, or both, depending on where your account holders bank:

To launch the SDK, your backend provides the token it needs. For the Web SDK, use your client level access token to request a single-use SLA token for the sender (see Web SDK authentication). For native SDKs, provide a "Sender level" access token (see the section above on authentication).

Once the user launches the PayMitto SDK, the entire transfer flow is owned and maintained by PayMitto up to the point of submitting the Transfer.

Step 5: Secure funds

Once the user reviews and accepts the Transfer details, the PayMitto SDK sends the transfer details to your frontend (the create-transfer callback in the Web SDK, or the READYREMIT_TRANSFER_SUBMITTED callback in the native SDKs). The request body in this callback payload should be sent to your backend for final submission to the PayMitto API. Optionally, you can prompt the user for a One Time Password (OTP) or other two-factor authentication (2FA) at this point. Before sending the API call to PayMitto though, you must take any necessary action to ensure that funds are available for the Transfer and these funds are made unavailable to the Sender.

The amount to secure can be found in the payload from the PayMitto SDK in the amount field of the quote object.

🚧

Decimal normalization

Be aware that the value in the amount field of the quote is "decimal normalized" to eliminate any programming language errors. For more information on how to interpret currencies in the PayMitto API, see this page in the documentation.

Step 6: Submit the transfer

Once funds have been secured, get a fresh "Sender level" access token and call the Create Transfer API to create the final Transfer.

The result of the Transfer creation includes a "Transfer ID" that can be saved and used later to show transfer details to your user.

The response from the Create Transfer API will include the full details of the transfer and a transferId. This Transfer ID must be returned to the PayMitto SDK in order to finalize the transfer flow.

Important: If there is any failure returned from the Create Transfer API call, the funds should be credited back to theSender and a user readable error message returned back to the PayMitto SDK.

Next steps

Once you've finished here, these pages are good places to go next:

Updated about 13 hours ago

Did this page help you?