Embedded API Integration

The embedded solution requires you to integrate with the i-payout API to create beneficiaries and transfer funds to them. This page guides you through the endpoints needed to perform this integration.

📘

API Reference

The main endpoints in this guide are crucial for integrating and using i-payout. Explore our API Reference to access and learn all the different methods available for managing your beneficiaries and transfers.

Step 1: API Token

The Embedded solution will require you to use two different API Tokens. One is for calling the i-payout API, and the other is to grant you access to the embedded components.

Token for API Calls

i-payout offers two different tokens you can generate and use to call i-payout's API. Refer to the Get a Token guide to learn how to:

Embedded Token

Use the Get Embedded Token endpoint to generate a token that allows access to the embedded components. You will use this token in the How to Use the UI Components guide.

Step 2: Create a Beneficiary

A beneficiary is an individual designated to receive funds or payments through the i-payout system. To create a beneficiary, you will need to provide detailed information about the individual, such as their name, address, and payment details.

Use the Create Beneficiary endpoint to create a new beneficiary. The request should include all necessary details about the beneficiary in the request body and, as shown in Step 1, include the authentication to access the i-payout API. Below, you will find an example request to create a new beneficiary:

curl --request POST \
     --url https://merchantapi.testewallet.com/api/v1/beneficiaries \
     --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
     --header 'X-MerchantId: <YOUR_MERCHANT_ID>' \
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --data '{
        "username": "john_doe",
        "firstName": "John",
        "lastName": "Doe"
    }'

{
  "data": {
    "customerToken": "e0e4764b-9619-4deb-95c4-108ce9f0fe04"
  },
  "isSuccess": true,
  "message": "Customer created successfully",
  "statusCode": 0,
  "logIdentifier": "497b73624c0d47bfb0abf58df5dd99ca"
},

The response will return a 200 status code, and in the response's body, you can find the beneficiaryToken, which you will use later on in this guide.

Step 3: Create a Transfer Method with UI Components

This is where the full API integration and the Embedded Solution differ. In the Embedded Solution, you will follow the guide on How to Use the UI Components to add the embedded components that handle sensitive information to your website. After you've done that, you can proceed to the next step.

Step 4: Transfer Funds to a Beneficiary

Now, you need to pay the new beneficiaries created in the system. This is done by transferring funds to them. The Create Transfer endpoint will be used to make the transfer from you to your beneficiary by linking the transfer with the beneficiaryToken created on Step 2. Below, you will find an example request to create a new transfer:

curl --request POST \
     --url "https://merchantapi.testewallet.com/api/v1/transfers" \
     --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
     --header 'X-MerchantId: <YOUR_MERCHANT_ID>' \
     --header "accept: application/json" \
     --header "Content-Type: application/json" \
     --data '{
          "merchantTransactionId": "TX123456",
          "beneficiaryToken": "<beneficiaryToken_from_step_2>",
          "autoApprove": true,
          "comments": "Payment for services",
          "dateExpire": "2024-12-31T23:59:59.999Z",
          "destinationAmount": 100.00,
          "destinationCurrency": "USD",
          "destinationType": "RegularACH",
          "bankAccount": {
              "accountNickName": "John Personal Account",
              "accountCurrency": "USD",
              "accountNumber": "123456789",
              "accountType1": "personal",
              "accountType2": "checking",
              "bankName": "Bank of America",
              "bankCountry": "US",
              "routingNumber": "987654321",
              "branchAddress": "1234 Bank Street, Suite 567",
              "beneficiaryCountry": "US",
              "beneficiaryAddress1": "1234 Elm St",
              "beneficiaryState": "CA",
              "beneficiaryCity": "Los Angeles",
              "beneficiaryZipCode": "90001",
          },
     }'

{
  "isSuccess": true,
  "message": "Transfer created successfully",
  "statusCode": 200,
  "logIdentifier": "abc123def456",
  "token": "trans789token",
  "dateCreated": "2024-07-09T16:17:00.548Z",
  "dateUpdated": "2024-07-09T16:17:00.548Z",
  "statusId": 1,
  "fxRate": 1.05,
  "customerFee": 2.50,
  "merchantFee": 1.00
}

📘

Auto Approve

If you set the autoApprove flag to false, you will need to approve the transfer with the Approve or Cancel Transfer endpoint, with the token found in the creation response to approve the transfer.

Webhooks

Set up webhooks to receive real-time notifications about various events related to i-payout. By configuring webhooks, you can automate your workflow, reduce manual checks, and immediately inform you of important events. Learn more about i-payout Webhooks here.

Next Step

With your system integrated with i-payout API, it's time to learn how to add and use our UI components on your website:

• How to Use the UI Components