Guides

How to Collect a Receivable from a Hosted Solution Beneficiary

Suggest Edits

The usual workflow for collecting a receivable from a hosted solution beneficiary involves the following steps:

Step 1: Authenticate: Obtain an API token by validating your credentials.

Step 2: Create Beneficiary: Create a new beneficiary using the API.

Step 3: Create Payment Item: Set up the items that the beneficiary will pay.

Step 4: Subscribe to Webhook: Set up webhooks to receive notifications about payment events.

API Endpoints Used

In this guide, you will use the following API endpoints:

Get API Token

Create Beneficiary

Create Payment Item

Create Webhook

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

📘

Recipe

You can also follow our recipe by clicking the link below:

🦉
How to Collect a Receivable from a Hosted Solution Beneficiary
Open Recipe

Step 1: Authenticate

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 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"
    }'

{
  "isSuccess": true,
  "message": "Beneficiary created successfully",
  "statusCode": 0,
  "logIdentifier": "497b73624c0d47bfb0abf58df5dd99ca",
  "data": {
    "beneficiaryToken": "556bb43b-7395-4bf9-ab5e-108ce9f0fe04"
  }
}

Step 3: Create Payment Item

After creating a beneficiary, you need to set up the payment items that the beneficiary will pay for. Use the Create Payment Items endpoint to create these items. Below, you will find an example request to create payment items:

curl --request POST \
     --url "https://merchantapi.testewallet.com/api/v1/payins" \
     --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
     --header 'X-MerchantId: <YOUR_MERCHANT_ID>' \
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --data '{
         "items": [
             {
                 "description": "Service Fee",
                 "amount": 50.00,
                 "currency": "USD"
             },
             {
                 "description": "Product Purchase",
                 "amount": 150.00,
                 "currency": "USD"
             }
         ],
         "beneficiaryToken": "556bb43b-7395-4bf9-ab5e-108ce9f0fe04"
     }'

{
  "isSuccess": true,
  "message": "Payment items created successfully",
  "statusCode": 200,
  "logIdentifier": "abc123def456",
  "data": {
    "paymentItems": [
      {
        "itemId": "item001",
        "description": "Service Fee",
        "amount": 50.00,
        "currency": "USD"
      },
      {
        "itemId": "item002",
        "description": "Product Purchase",
        "amount": 150.00,
        "currency": "USD"
      }
    ]
  }
}

Step 4: Subscribe to Webhook

To receive real-time notifications about various payment events, you need to set up webhooks. Use the Create Webhook endpoint to create a webhook subscription. For more detailed instructions, see the How to Setup Webhooks guide. Below, you will find an example request to create a webhook:

curl --request POST \
     --url "https://merchantapi.testewallet.com/api/v1/webhooks" \
     --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
     --header 'X-MerchantId: <YOUR_MERCHANT_ID>' \
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --data '{
         "event": "PAYMENT.COMPLETED",
         "url": "https://yourwebhookurl.com/notification",
         "description": "Webhook for payment completion"
     }'

{
  "isSuccess": true,
  "message": "Webhook created successfully",
  "statusCode": 200,
  "logIdentifier": "xyz789hij012",
  "data": {
    "webhookToken": "webhooktoken123",
    "event": "PAYMENT.COMPLETED",
    "url": "https://yourwebhookurl.com/notification",
    "status": "active"
  }
}

🚧

Webhook URL

Ensure that your webhook URL is accessible and can handle the incoming notifications appropriately.

Updated 22 days ago