--- title: "Partial Payments" source_url: https://docs.rapyd.net/en/partial-payments.html lang: en --- # 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](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_pos "Point of Sale") 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](image/img-1ed2d6131f39f342450b1ff90c1f1f3e.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](image/img-ded0dfbb5c6de910d431f6b647a92f7b.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](image/img-e827d33993ecbe3d43a946e1b9a0b600.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](https://docs.rapyd.net/en/list-payment-methods-by-country.md "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¤cy=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](https://docs.rapyd.net/en/get-payment-method-required-fields.md "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](https://docs.rapyd.net/en/create-payment.md "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 > **Note:** > > 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. > **Note:** > > Want to see the Rapyd API methods and objects that you'll use? Visit the [Merchant API Reference](https://docs.rapyd.net/en/merchant-api-reference.md "Merchant API Reference") for more technical details.