Operation Types and the Sequence of API Calls

Agent API Overview

The Agent API allows merchants to facilitate peer-to-peer (P2P) payments or make payouts to their clients by using an agent as an intermediary. The agent receives funds from the client on behalf of the merchant or makes payouts to the client from the merchant.

Key Concepts

1. Merchant: The business entity that integrates with the Agent API to receive payments or make payouts to their end clients through the agent.
2. Agent: The intermediary that handles the transaction, receiving funds from the merchant's client or making payouts to the merchant's clients on behalf of the merchant.
3. Client: The end customer making the payment or receiving the payout on behalf of the merchant.

Overview

The operationType parameter in our API is crucial for defining the type of transaction being processed. It distinguishes between two main types of financial operations: payin and payout.

Operation Types

The operationType parameter allows you to specify two primary types of operations:

1. Payin: This is when the payer transfers funds to the Agent's account on behalf of the merchant.
2. Payout: This refers to the disbursement of funds by the Agent to the designated account as instructed by the merchant.

API Sequence Calls

1. Pay-in and the Sequence of API Calls

• Description: A payin operation records the acceptance of funds by the Agent from the end payer or buyer on behalf of the Merchant. This transaction type is typically used when a customer pays for a service or product.

Process:

1. Get available payment method types: Request a list of available payin operations for your store.
2. Select a suitable payment method for your transaction.
3. Initialize a new session: Initialize a session by providing the paymentMethodTypeId obtained from the previous step.
4. Create operation: Create an operation by submitting all necessary information:
   • sessionId - The unique identifier of the session obtained from the response in the previous step.
   • payerRequisites - The payer's details required for the operation. You need to pass all the data from the payerRequisites array object obtained in the response of the previous step, adding a field called value and filling it with the payer's information, so the Agent can identify the P2P money transfer operation.
5. In the response received from the Create operation endpoint, you will get the details of the operation. The operation will be assigned the status created.
6. A Callback will be sent when the order status changes.
7. To manually verify the status and specific details of your operation, use the Retrieve Operation Details endpoint.
8. In the response from the Create operation and the Retrieve Operation Details endpoints, you will find an array of paymentMethodRequisites objects. You need to show this data to the payer so they can transfer the funds to the Agent using these details.
9. After receiving the funds, the Agent will confirm the operation, and its status will change to captured.

2. Payout and the Sequence of API Calls

• Description: The payout operation involves the transfer of funds by the Agent to the merchant's client.

Process:

1. Get available payment methods: Request a list of available payout operations.
2. Select an appropriate payment method for your transaction.
3. Initialize a new session: Initialize a session by providing the paymentMethodTypeId obtained from the previous step.
4. Create operation: Create an order by providing all necessary information:
   • sessionId - The unique identifier of the session.
   • payerRequisites - The payer's details required for the operation. You need to pass all the data from the payerRequisites array object obtained in the response of the previous step, adding a field called value and filling it with the recipient's information, so the Agent can perform the P2P payout operation based on this data.
5. In the response received from the Create operation endpoint, you will get the details of the operation. The order will be assigned the status created.
6. A Callback will be sent when the order status changes.
7. To manually verify the status and specific details of your operation, use the Retrieve Operation Details endpoint.
8. In the response from the Create operation and the Retrieve Operation Details endpoints, you will find an array of paymentMethodRequisites objects. You need to show this data to the payer so they can verify that the funds have been received from the Agent.
9. After sending the funds, the Agent will confirm the operation, and its status will change to captured.