Guides

Full API Integration

Suggest Edits

Fully integrating with our API allows your application to connect seamlessly with all the services provided by i-payout. This means that users can perform transactions directly within your application without interacting with i-payout's eWallet interface. By handling everything programmatically, you ensure a smooth and cohesive user experience. Below are the main steps for this integration:

  1. Authentication: Obtain an API token by validating your credentials.
  2. Beneficiary Management: Create and manage beneficiary's accounts using API calls.
  3. Transfer Methods: Add and manage transfer methods for your beneficiaries.
  4. Transfers: Execute and manage transfers between accounts.

Below, you will go through the necessary API calls to achieve the steps above within the i-payout system.

📘

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

To start using i-payout solutions, you will need to authenticate with your API Token. Refer to the Get a Token guide to learn how to:

Obtain a Token through the API

Obtain a Token through the i-payout Admin Portal

Use your API Token

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 the Get API Token guide, 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": {
    "beneficiaryToken": "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

You need to create a transfer method to manage how funds are transferred to beneficiaries. This step involves adding specific transfer details to the beneficiary profile, such as bank accounts, wire transfer details, or credit card information. Here’s an example of how you can get the token you will need to perform the transaction:

Adding a Bank Account Transfer Method

To add a bank account as a transfer method, use the Add Bank Account endpoint. This allows you to specify the beneficiary's bank account details, ensuring that funds are correctly directed to their bank account. Below, you will find an example request to add a bank account:

curl --request POST \
     --url "https://merchantapi.testewallet.com/api/v1/transfermethods/beneficiaries/<BENEFICIARY_TOKEN_FROM_STEP_2>/bank-accounts" \
     --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
     --header 'X-MerchantId: <YOUR_MERCHANT_ID>' \
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --data '{
        "beneficiaryToken": "<beneficiaryToken_from_step_2>",
        "accountHolderName": "John Doe",
        "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",
        "beneficiaryFirstName": "John",
        "beneficiaryLastName": "Doe",
        "beneficiaryCountry": "US",
        "beneficiaryAddress1": "1234 Elm St",
        "beneficiaryState": "CA",
        "beneficiaryCity": "Los Angeles",
        "beneficiaryZipCode": "90001",
     }'

{
  "isSuccess": true,
  "message": "Bank account added successfully",
  "statusCode": 200,
  "logIdentifier": "def456ghi789",
  "token": "bankAcc123Token",
  "dateCreated": "2024-07-20T10:00:00.000Z",
  "dateUpdated": "2024-07-20T10:00:00.000Z"
}

Retrieving a Bank Account

If your beneficiary is already registered, you can simply retrieve the details of an existing transfer method using the Get Bank Account endpoint. This lets you view a beneficiary token's stored bank account information. Below, you will find an example request to retrieve a bank account:

curl --request GET \
     --url https://merchantapi.testewallet.com/api/v1/transfermethods/beneficiaries/<BENEFICIARY_TOKEN>/bank-accounts/<BANK_ACCOUNT_TOKEN> \
     --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
     --header 'X-MerchantId: <YOUR_MERCHANT_ID>' \
     --header 'accept: application/json' \
     --data '{
         "beneficiaryToken": "<beneficiaryToken_from_step_2>"
     }'

{
  "isSuccess": true,
  "message": "Bank account retrieved successfully",
  "statusCode": 200,
  "logIdentifier": "ghi789jkl012",
  "data": {
    "accountHolderName": "John Doe",
    "accountNumber": "123456789",
    "bankName": "Bank of the World",
    "routingNumber": "987654321",
    "countryCode": "US",
    "currencyCode": "USD",
    "token": "bankAcc123Token"
  }
}

Both methods return a response with a token, which you will use in the next step.

Step 4: Transfer Funds to a Beneficiary

Once you have the payment method token, you can pay the beneficiary. 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 and the token created on Step 3, which in this step is called destinationToken. 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 use the Approve 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.

Updated 21 days ago