Skip to main content

Documentation

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
customer-checkout-cash.jpg

  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
process-the-payment.jpg

  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
tracking-cash-payment.jpg

  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.

How Partial Payments Work
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 USD (U.S. Dollars).

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

Description of Query 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

      • // 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.

    • 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: 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:

Description of Path Parameters

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

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

// Message body absent
Get Payment Method Required Fields Response

Let's take a look at the response.

    • 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 requesting Rapyd to process a cash payment, you'll use Create Payment with the following parameters:

Description of Body 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 the 9.99 USD (U.S. Dollars) payment as a cash transaction.

    • Request

      • // 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.

    • 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 (U.S. Dollars).

  • The status is ACT (active). This means that the payment process is active but not complete.

  • 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 the partial payment is made:

  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.

    • PAYMENT_COMPLETED webhook

      • {
        "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": "johndoe@rapyd.net",
                "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 to the customer to complete the 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 API Reference for more technical details.

In this section:

A retail location where a business or consumer can initiate a transaction in exchange for goods or services.