Partial Payments

Customers can pay for purchases using more than one payment method such as cash and a bank transfer.

Sometimes a customer chooses to pay by cash or bank transfer and then pays only part of the required amount. This use case explores this issue. When the partial payment is made, Rapyd closes the transaction and sends you a webhook with the details.

A customer chooses “pay with cash” on your payment page for an item they’ve added to their shopping cart.

The customer goes to a nearby over-the-counter POS location, shows the payment reference number to the cashier, and pays in cash, but only part of the amount required. The Rapyd platform notifies your website back end that the payment was completed only partially. Your website notifies the customer of the steps required to complete the purchase.

Cash Payment Workflow

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

Step 1 - Customer Checkout for a Cash Payment

  1. A customer on your website adds an eBook to the shopping cart and presses the checkout button.
  2. The website displays payment method options.
  3. The customer selects a cash payment method and clicks Pay.

Step 2 - Processing the Payment

  1. Your website back end asks Rapyd to create a cash payment.
  2. Rapyd processes the transaction and responds with details of the transaction and instructions for the customer.
  3. Your website displays the instructions for payment, including the amount and reference number.

Step 3 - Tracking the Cash Payment

  1. The customer goes to the point-of-sale location, shows the payment reference number, and pays in cash.
  2. The point-of-sale location notifies Rapyd that the cash was received.
  3. Rapyd notifies your website back end that the payment is partial and closed.
  4. You ask the customer for the remaining money due for the purchase.

Finding Available Payment Methods

On your payment page, you let the customer specify payment methods. First, you need to decide which payment methods you'll accept. In this example, you'll check for cash payment methods using US dollars.

For that, you'll use List Payment Methods by Country with the following parameters:

Query Parameter

Description

country

Enter US as the country code.

currency

Enter USD as the currency code.

List Payment Methods by Country request

You ask for the list of all available US payment methods.

// Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/country?country=US&currency=USD

// Message body absent

List Payment Methods by Country response

Let's take a look at the response. Payment Method Object describes the fields in the response.

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "cfa35a73-aa0b-4e7e-839c-4c3b6149edd7"
    },
    "data": [{
            "type": "us_moneygram_cash",
            "name": "MoneyGram",
            "category": "cash",
            "image": "https://iconslib.rapyd.net/checkout/us_moneygram_cash.png",
            "country": "us",
            "payment_flow_type": "cash",
            "currencies": [
                "USD"
            ],
            "status": 1,
            "is_cancelable": false,
            "payment_options": [],
            "is_expirable": false,
            "is_online": false,
            "minimum_expiration_seconds": null,
            "maximum_expiration_seconds": null
        }
    ]
}

The response shows that us_moneygram_cash is an acceptable payment method.

Note that a real response usually lists many payment methods.

Finding Required Fields for the Payment Method

You need to find which fields the customer must fill in for the payment method.

For that, you'll use the Get Payment Method Required Fields with the following parameter:

Path Parameter

Description

type

Enter us_moneygram_cash as the payment method type.

Get Payment Method Required Fields request

You ask for the set of required fields for a MoneyGram cash payment.

// Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/required_fields/us_moneygram_cash

// Message body absent

Get Payment Method Required Fields response

Let's take a look at the response. Payment Method Object describes the fields in the response.

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "be4d09f5-db63-43b9-8486-6d91a9c816cc"
    },
    "data": {
        "type": "us_moneygram_cash",
        "fields": [],
        "payment_method_options": [],
        "payment_options": [],
        "minimum_expiration_seconds": null,
        "maximum_expiration_seconds": null
    }
}

The response shows that no fields are required for a MoneyGram cash payment.

Processing the Cash Payment

When John Doe checks out on your website, you ask Rapyd to process his cash payment.

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

Body Parameter

Description

payment_method

Enter an object with the following field:
type - us_moneygram_cash

amount

Enter 9.99 as the payment amount.

currency

Enter USD as the currency code.

Create Payment request

You ask Rapyd to process John's $9.99 payment as a cash transaction.

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

// Message body:
{
    "amount": 9.99,
    "currency": "USD",
    "payment_method": {
        "type": "us_moneygram_cash",
        "fields": {}
   }
}

Create Payment response

Let's take a look at the response. Payment Object describes the fields in the response.

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "b98b2e90-aefd-48b2-aa0e-785b33640240"
    },
    "data": {
        "id": "payment_809838a4ff531cbeba84c04426c03d4a",
        "amount": 0,
        "original_amount": 9.99,
        "is_partial": false,
        "currency_code": "USD",
        "country_code": "us",
        "status": "ACT",

        //      ...

        "customer_token": "cus_d9cb9eb9e3f09f94d507ad62cb897441",
        "payment_method": "other_08dba6d49d5c52b8d9b9647f22dea8f8",

        //      ...

        "captured": true,

        //      ...

        "created_at": 1585569886,

        //      ...

        "paid": false,
        "paid_at": 0,

        //      ...

        "visual_codes": {},
        "textual_codes": {
            "code": "8765434427478124"
        },
        "instructions": [
            {
                "name": "instructions",
                "steps": [
                    {
                        "step1": "Scan or show your transaction code to the cashier and pay the amount"
                    }
                ]
            }
        ],

        //      ...

        "payment_method_type": "us_moneygram_cash",
        "payment_method_type_category": "cash",

        //      ...

    }
}

The data section of this response shows:

  • The payment id is payment_809838a4ff531cbeba84c04426c03d4a. 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 original_amount is 9.99.
  • The currency_code is USD (United States dollars).
  • The status is ACT (active). This means that the payment process is active but not complete. Payment Object lists possible values for status.
  • The code for the one-time payment reference is 8765434427478124.
    In this example, the payment code is a number in string format. Payment codes also can be bar codes or QR codes.
  • There are instructions for your customer.

Your website shows the customer the amount to pay, the payment reference number, and the instructions.

Closing the Transaction

🚧

Simulating a Cash Payment

It is not possible to simulate a partial payment.

After John pays the partial amount:

  1. The point-of-sale location informs Rapyd that the partial payment payment was received.
  2. Rapyd sends you a webhook with the details of the completed transaction.
{
    "id": "wh_e5f1259ae010a68c1bf191bbf8562a6c",
    "type": "PAYMENT_COMPLETED",
    "data": {
          "id": "payment_809838a4ff531cbeba84c04426c03d4a",
          "paid": true,
          "order": null,
          "amount": 5.49,
          "escrow": {
            "id": "",
            "status": "",
            "payment": "payment_809838a4ff531cbeba84c04426c03d4a",
            "created_at": 0,
            "updated_at": 0,
            "amount_on_hold": 0,
            "escrow_release_days": null,
            "total_amount_released": 0,
            "last_payment_completion": null
      }
        },
        "status": "CLO",
        "address": {
            "id": "address_8585f183015c79056aaac81f404377cf",
            "zip": "12345",
            "city": "Anytown",
            "name": "John Doe",
            "state": "NY",
            "canton": "",
            "line_1": "123 Main Street",
            "line_2": "",
            "line_3": "",
            "country": "USA",
            "district": "",
            "metadata": {},
            "created_at": 1570705044,
            "phone_number": "+11570705033"
        },
        "dispute": null,
        "fx_rate": "",
        "invoice": "",
        "outcome": null,
        "paid_at": 1570705044,
        "refunds": null,
        "captured": null,
        "ewallets": [{
                "amount": 5.49,
                "percent": 100,
                "ewallet_id": "ewallet_a9fc4a9abf57b62986ac278466c6e45e",
                "refunded_amount": 0,
                "released_amount": 0
            }
        ],
        "metadata": {
        "merchant_defined": true
    },
        "refunded": false,
        "flow_type": "",
        "created_at": 1570705044,
        "ewallet_id": "ewallet_a9fc4a9abf57b62986ac278466c6e45e",
        "expiration": 1573296810,
        "is_partial": true,
        "description": "The payment is partially complete.",
        "country_code": "US",
        "failure_code": "",
        "instructions": [],
        "payment_fees": null,
        "redirect_url": "",
        "visual_codes": {},
        "currency_code": "USD",
        "group_payment": "",
        "receipt_email": "[email protected]",
        "textual_codes": {},
        "customer_token": "cus_d9cb9eb9e3f09f94d507ad62cb897441",
        "payment_method": "other_08dba6d49d5c52b8d9b9647f22dea8f8",
        "receipt_number": "",
        "transaction_id": "",
        "failure_message": "",
        "original_amount": 25.25,
        "refunded_amount": 0,
        "error_payment_url": "https://www.computerhope.com/jargon/e/error.gif",
        "payment_method_type": "us_moneygram_cash",
        "complete_payment_url": "http://www.complete.com/images/complete-logo-website.svg",
        "statement_descriptor": "statement_1570705033",
        "merchant_reference_id": "2311-1570705033",
        "payment_method_options": {},
        "merchant_requested_amount": null,
        "merchant_requested_currency": null,
        "payment_method_type_category": "card"
    },
    "trigger_operation_id": "c5dc010e-48ab-4ed2-b2d3-b08481bf32db",
    "status": "NEW",
    "created_at": 1570705046
}

Note the following data:

  • status - CLO - This indicates that the transaction is closed.
  • amount - 5.49 - This is less than the amount the payment was created for.
  • is_partial - true - This indicates that the full amount of the payment was not received.

Now you can display a page telling John Doe what he must do to complete his purchase of the eBook.

📘

Looking for more in-depth technical information?

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

Updated about a month ago


What's Next

Modify Payments

Partial Payments


Customers can pay for purchases using more than one payment method such as cash and a bank transfer.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.