Refund to Multiple Accounts

When multiple sellers are involved in a single transaction, you can send a refund from one seller.

Rapyd provides a quick and easy method for processing partial refunds of a purchase made by a customer on your eCommerce website.

You can make partial refunds multiple times for the same purchase.

Refunds are made to the payment method used in the original payment transaction. In this use case, the customer paid by card to multiple sellers (wallets) and a partial refund was made from a specific seller (wallet).

PCI Certification

Only clients with PCI-DSS certification can handle personal identifying information for cards. This method is available to merchants who have signed a special agreement with Rapyd.

The customer uses a card to buy a speaker and a phone from two sellers on your marketplace website. Later on, the customer requests a partial refund from the seller of the speaker since the speaker wasn't the exact color that was advertised.

Your website back end asks Rapyd to process the partial refund from the Wallet of the speaker seller. When the money is returned to the customer's card, Rapyd notifies you that the partial refund was completed successfully.

Making a Partial Refund Workflow

Finding the specific bank transfer payment methods you'll accept and the corresponding required fields that customers fill out is described under How it Works.

Step 1: Processing the Payment

A customer on your marketplace website purchases two products from two different sellers.
The website back end asks Rapyd to process the transaction.
Rapyd processes the payment.

Step 2: Processing the Partial Refund

The customer fills in all the fields required by your website's Refund Request page to receive a partial refund from one seller. You have the ID of the transaction and the amount that needs to be refunded.

The customer asks the merchant for a partial refund.
Your website backend requests Rapyd to process the customer's partial refund.
Rapyd processes the refund transaction and notifies you that it was successful and then you send confirmation of the refund to the customer.

How Refunds to Multiple Accounts Work

Prerequisites

To run the examples of this use case, you must create the following IDs in your own sandbox:

'ewallet' - Run Create Wallet for the wallet of the seller of the phone. Use the 'id' you get in the response. Repeat for the wallet of the seller of the speaker.

Find Available Payment Methods

Decide which payment methods you'll accept. See List Payment Methods by Country .

List Payment Methods by Country Request

Find the required fields that customers must fill in for each payment method. See Get Payment Method Required Fields .

Creating the Payment

The customer makes these purchases on your marketplace website:

A speaker from one seller for 50.00 USD (U.S. Dollars).
A phone from another seller for 200.00 USD (U.S. Dollars).

You ask Rapyd to process the payment.

For that, you'll use Create Payment with the following parameters:

Description of Body Parameters

Body Parameter	Description
amount	Enter 250 as the total amount of the payment.
currency	Enter USD as the code for U.S. Dollars.
payment_method	Enter a 'payment_method' object that has the following fields:...`cvv` - Enter 123.`name` - Enter Test User. `type` - Enter us_debit_visa_card as the type of payment method. `fields` - Enter an object that has the following fields. The fields are defined in the 'Get Payment Method Required Fields' response for us_debit_visa_card. `number` - Enter 4111111111111111 . `expiration_month` - Enter 10 `expiration_year` - Enter 20 `cvv` - Enter 123. `name` - Enter Test User .
ewallets	Enter an array of the following objects: First object: `ewallet` - Enter the wallet 'id' that you received when you created the speaker seller's wallet in your sandbox. For purposes of this use case lesson, we are using ewallet_090e1ef18c3aa754fd43cce9ee454858, which is the wallet ID we created in our sandbox. `amount` - Enter 50 as the amount to pay the speaker seller Second object: `ewallet` - Enter the wallet 'id' that you received when you created the speaker seller's wallet in your sandbox. For purposes of this use case lesson, we are using ewallet_11078019438f943986c1fcfbaba05e13, which is the wallet ID we created in our sandbox. `amount` - Enter 200 as the amount to pay the phone seller.

Create Payment Request

You ask Rapyd to process the payment.

Request

// Request URL: POST https://sandboxapi.rapyd.net/v1/payments

// Message body:
{
        "amount": 250,
        "currency": "USD",
        "payment_method": {
                "type": "us_debit_visa_card",
                "fields": {
                        "number": "4111111111111111",
                        "expiration_month": "10",
                        "expiration_year": "20",
                        "cvv": "123",
                        "name": "Test User"
                }
        },
        "ewallets": [
                {
                        "ewallet": "ewallet_090e1ef18c3aa754fd43cce9ee454858",
                        "amount": 50
                }, 
    {
                        "ewallet": "ewallet_11078019438f943986c1fcfbaba05e13",
                        "amount": 200
                }
        ]
}

.NET Core

using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                var requestObj = new
                {
                    amount = 250,
                    currency = "USD",
                    payment_method = new
                    {
                        type = "us_visa_card",
                        number = "4111111111111111",
                        expiration_month = "10",
                        expiration_year = "20",
                        cvv = "123",
                        name = "John Doe",
                    },
                    ewallets = new Object[]
                    {
                        new
                        {
                            ewallet = "ewallet_090e1ef18c3aa754fd43cce9ee454858",
                            amount = 50
                        },
                        new
                        {
                            ewallet = "ewallet_11078019438f943986c1fcfbaba05e13",
                            amount = 200
                        },
                    },
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/payments", request);

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}

Python

from pprint import pprint

from utilities import make_request

payment_body = {
    "amount": 250,
    "currency": "USD",
    "payment_method": {
        "type": "us_visa_card",
        "fields": {
            "number": "4111111111111111",
            "expiration_month": "10",
            "expiration_year": "20",
            "cvv": "123",
            "name": "John Doe"
        }
    },
    "ewallets": [
        {
            "ewallet": "ewallet_090e1ef18c3aa754fd43cce9ee454858",
            "amount": 50
        },
        {
            "ewallet": "ewallet_11078019438f943986c1fcfbaba05e13",
            "amount": 200
        }
    ]
}

create_payment_response = make_request(method='post', path='/v1/payments', body=payment_body)
pprint(create_payment_response)

Create Payment Response

Let's take a look at the response.

Response

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "d584c716-0e2d-47aa-a85d-8e8d99f4ee45"
    },
    "data": {
        "id": "payment_a257811affe292c98c8bb6693e8b8cf0",
        "amount": 250,
        "original_amount": 250,
        "is_partial": false,
        "currency_code": "USD",
        "country_code": "US",
        "status": "CLO",
        "description": "",
        "merchant_reference_id": "",
        "customer_token": "cus_8aeff2ec08a57b44e4442786276d4ef2",
        "payment_method": "card_d25e29a0cdb7866766bb2c2528cd49e3",
        
//  ...
          
        "created_at": 1581246669,
        "metadata": {},
        "failure_code": "",
        "failure_message": "",
        "paid": true,
        "paid_at": 1581246670,
        
//  ...          
          
        "ewallets": [
            {
                "ewallet_id": "ewallet_090e1ef18c3aa754fd43cce9ee454858",
                "amount": 50,
                "percent": 20,
                "refunded_amount": 0
            },
            {
                "ewallet_id": "ewallet_11078019438f943986c1fcfbaba05e13",
                "amount": 200,
                "percent": 80,
                "refunded_amount": 0
            }
        ],
        "payment_method_options": {},
        "payment_method_type": "us_debit_visa_card",
        "payment_method_type_category": "card",
       
//    ...
          
    }
}

The data section of this response shows that:

The payment id is payment_a257811affe292c98c8bb6693e8b8cf0. When you run this example in your own sandbox, you will get a different ID, which you will need for a later step in this use case.
The amount is 250.
The currency is USD.
The ewallets object indicates:
- An amount of 50 is paid to ewallet_id ewallet_090e1ef18c3aa754fd43cce9ee454858.
- An amount of 200 is paid to ewallet_id ewallet_11078019438f943986c1fcfbaba05e13.

You will use the payment id and speaker seller's ewallet_id when you ask Rapyd to partially refund the payment of the speaker seller.

Creating the Refund

The customer requests a partial refund from the speaker seller since the speaker wasn't the exact color that was advertised, and your terms of service allow a ten percent partial refund in such circumstances.

When the customer requests a partial refund on your website, you ask Rapyd to process the refund.

For that, you'll use Create Refund with the following parameters:

Description of Body Parameters

Body Parameter	Description
payment	Enter the payment 'id' that you received when you created the payment in your sandbox. For purposes of this use case lesson, we are using payment_a257811affe292c98c8bb6693e8b8cf0, which is the payment ID we created in our sandbox.
ewallets	Enter an `ewallets` object that has the following fields: `ewallet` - Enter the wallet 'id' that you received when you created the speaker seller's wallet in your sandbox. For purposes of this use case lesson, we are using ewallet_090e1ef18c3aa754fd43cce9ee454858, which is the wallet ID we created in our sandbox. `amount` - Enter 5 as the amount to refund the customer.

Create Refund Request

You ask Rapyd to process the refund of the earlier transaction.

Request

// Request URL: POST https://sandboxapi.rapyd.net/v1/refunds

// Message body:
{
    "payment": "payment_a257811affe292c98c8bb6693e8b8cf0",
    "ewallets": [
        {
            "ewallet": "ewallet_090e1ef18c3aa754fd43cce9ee454858",
            "amount": 5
        }
    ]
}

.NET Core

using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                var requestObj = new
                {
                    payment = "payment_a257811affe292c98c8bb6693e8b8cf0",
                    ewallets = new Object[]
                    {
                        new {
                            ewallet = "ewallet_090e1ef18c3aa754fd43cce9ee454858",
                            amount = 5,
                        }
                    }
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/refunds", request);

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}

JavaScript

const makeRequest = require('../../../../../Utilities/JS/utilities').makeRequest;

async function main() {
  try {
    const body = {
      payment: 'payment_a257811affe292c98c8bb6693e8b8cf0',
      ewallets: [
        {
          ewallet: 'ewallet_090e1ef18c3aa754fd43cce9ee454858',
          amount: 5
        }
      ]
    };
    const result = await makeRequest('POST', '/v1/refunds', body);

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}

Python

from pprint import pprint

from utilities import make_request

refund_body = {
    "payment": "payment_a257811affe292c98c8bb6693e8b8cf0",
    "ewallets": [
        {
            "ewallet": "ewallet_090e1ef18c3aa754fd43cce9ee454858",
            "amount": 5
        }
    ]
}

create_refund_results = make_request(method='post',
                                     path='/v1/refunds',
                                     body=refund_body)

pprint(create_refund_results)

Create Refund Response

Let's take a look at the response.

Response

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "5356d170-951e-44d1-8bd5-fc5c6f110319"
    },
    "data": {
        "id": "refund_61a4c85a7cf7a7e631e454784ec4c579",
        "amount": 5,
        "payment": "payment_a257811affe292c98c8bb6693e8b8cf0",
        "currency": "USD",
        "failure_reason": "",
        "metadata": {},
        "reason": "",
        "status": "Completed",
        "receipt_number": 0,
        "created_at": 1581247161,
        "updated_at": 1581247161,
        "merchant_reference_id": "",
        "payment_created_at": 1581246669,
        "payment_method_type": "us_debit_visa_card",
        "ewallets": [
            {
                "ewallet": "ewallet_090e1ef18c3aa754fd43cce9ee454858",
                "amount": 5
            }
        ],
        "proportional_refund": false
    }
}

The data section of this response shows:

The id of the refund is refund_61a4c85a7cf7a7e631e454784ec4c579.
The amount is 5.
The currency is USD.
The status is Completed. This means that the refund process is complete.
In the ewallets object: The wallet charged is ewallet_090e1ef18c3aa754fd43cce9ee454858, the wallet of the speaker seller.

Note

If the payment was made by cash or a bank redirect, completing the refund process requires the same extra steps as the original payment method. To simulate the action of the customer, run Complete Refund.

Rapyd sends a webhook to notify you that the refund transaction is complete.

Your website shows the customer a confirmation that the partial refund is complete.

Viewing Transaction Details

To view the details of the payment and the refund, use Retrieve Payment.

Looking for More In-Depth Technical Information?

Want to see the Rapyd API methods and objects that you'll use? Visit the API Reference for more technical details.

In this section:

Documentation