---
title: "Cash Payments"
source_url: https://docs.rapyd.net/en/cash-payments.html
lang: en
---

# Cash Payments

Increase revenue by integrating a better cash collection system.

Rapyd's global cash-based over-the-counter network opens the world’s most popular payment method. Allow your customers to pay with cash on your website for an item they've added to their shopping cart.

Based on information exchanged with Rapyd, your website provides your customer with a payment reference number that can be displayed to the user as a QR code or barcode which can be scanned. 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.

### Cash Payment Checkout

1. Select the payment method.
2. Enter your name and email address.
3. Click **Place Your Order**.

   ![6480838765b2b.png](image/img-1970b047318c9df9be0014c6ab3d1cea.png)
4. Copy the transaction ID for your records.
5. Complete the payment instructions.
6. Click **Finish**.

   ![6480838a100f0.png](image/img-ca7e53e41ec9b509c8f8eedd6c1ee025.png)

### Cash Payment Workflow

Finding the specific cash payment methods at [POS](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_pos "Point of Sale") locations you'll accept and the corresponding required fields that customers fill out is described under How it Works.

### Step 1: Processing the Payment

![process-cash.jpg](image/img-e9a432a6a50a0f6ae9dd4ffc7352c594.jpg)

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

### Step 2: Tracking the Cash Payment

![track-cash.jpg](image/img-63f290798d9e953b58379312064a15a4.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 through a [Payment Completed Webhook](https://docs.rapyd.net/en/payment-completed-webhook.md "Payment Completed Webhook") that the payment was completed successfully.
4. You notify the customer that the purchase succeeded.

### Cash Payment Message Sequences

The message sequence diagrams below describe how information is exchanged between Rapyd, the merchant, the merchant's customers, and the POS.

Create Cash Payment - Success

![create-cash-payment---success.svg](image/img-9d9e34ec2fb725399754b893976ae0f3.svg)

Create Cash Payment - Expired

![create-cash-payment---expired.svg](image/img-181c692717ff0ca0f70690c959892066.svg)

### How Cash Payments Work

### Find Available Payment Methods

Decide the payment methods you will accept so your customer can specify their payment methods on your payment page. To do that, 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:

> **Note:**
>
> For illustration purposes, we will use PE (Peru) and PEN (Peruvian Peso) for country and currency in the sample codes below.

Description of Query Parameters

| Query Parameter | Description |
| --- | --- |
| country | Enter **PE** as the country code. |
| currency | Enter **PEN** as the currency code. |

### List Payment Methods by Country Request

Request a list of all available payment methods (PEN in this case).

- - Request

    - ```
      // Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/country?country=PE&currency=PEN

      // Message body absent
      ```
- - .NET Core

    - ```

      using System;

      namespace RapydApiRequestSample
      {
          class Program
          {
              static void Main(string[] args)
              {
                  try
                  {
                      string country = "PE";
                      string currency = "PEN";

                      string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payment_methods/country?country={country}&currency={currency}");

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

    - ```

      const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

      async function main() {
        try {
          const result = await makeRequest('GET', '/v1/payment_methods/country?country=PE&currency=PEN');

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

    - ```

      <?php
      $path = $_SERVER['DOCUMENT_ROOT'];
      $path .= "/<path-to-your-utility-file>/utilities.php";
      include($path);

      try {
          $object = make_request('get', '/v1/payment_methods/country?country=PE&currency=PEN');
          var_dump($object);
      } catch (Exception $e) {
          echo "Error: $e";
      }
      ?>
      ```
- - Python

    - ```
      from pprint import pprint

      from utilities import make_request

      country = 'PE'
      currency = 'PEN'
      results = make_request(method='get',
                             path=f'/v1/payment_methods/country?country={country}&currency={currency}')
      pprint(results)
      ```

### List Payment Methods by Country Response

[List Payment Methods by Country](https://docs.rapyd.net/en/list-payment-methods-by-country.md "List Payment Methods by Country") describes the fields in the response.

- - Response

    - ```
      {
         "status": {
             "error_code": "",
             "status": "SUCCESS",
             "message": "",
             "response_code": "",
             "operation_id": "a575ab97-c6ec-47f9-856d-0295f73ac6c2"
         },
         "data": [
      {
                 "type": "pe_cajaarequipa_cash",
                 "name": "Caja Arequipa Peru/Cash Payments",
                 "category": "cash",
                 "image": "https://iconslib.rapyd.net/checkout/pe_cajaarequipa_cash.png",
                 "country": "pe",
                 "payment_flow_type": "cash",
                 "currencies": [
                     "PEN”
                 ],
                 "status": 1,
                 "is_cancelable": false,
                 "payment_options": [
                     {
                         "name": "customer",
                         "type": "customer",
                         "regex": "",
                         "description": "make sure a customer was created with first_name, last_name and email",
                         "is_required": true,
                         "is_updatable": false
                     },
                     {
                         "name": "description",
                         "type": "string",
                         "regex": "",
                         "description": "the description field must be filled in.",
                         "is_required": true,
                         "is_updatable": false
                     },
                     {
                         "name": "expiration",
                         "type": "string",
                         "regex": "^[0-9]{10}$",
                         "is_required": true
                     }
                 ],
                 "is_expirable": false,
                 "is_online": false,
                 "minimum_expiration_seconds": null,
                 "maximum_expiration_seconds": null
             }
      ]
      }
         
      ```

The response shows that  **pe_cajaarequipa_cash** is an acceptable payment method in this case.

> **Note:**
>
> A full API response typically lists many payment methods.

### Find Required Fields for the Payment Method

Identify the fields that your customer needs to complete for the payment method. To do that, use [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  **pe_cajaarequipa_cash** as the payment method type. |

### Get Payment Method Required Fields Request

Request the set of required fields for a cash payment (Caja Arequipa Peru/Cash Payment in this case).

- - Request

    - ```
      // Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/pe_cajaarequipa_cash/required_fields

      // Message body absent
      ```
- - .NET Core

    - ```

      using System;

      namespace RapydApiRequestSample
      {
          class Program
          {
              static void Main(string[] args)
              {
                  try
                  {
                      string type = "pe_cajaarequipa_cash";

                      string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payment_methods/{type}/required_fields");

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

    - ```

      const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

      async function main() {
        try {
          const result = await makeRequest('GET', '/v1/payment_methods/pe_cajaarequipa_cash/required_fields');

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

    - ```

      <?php
      $path = $_SERVER['DOCUMENT_ROOT'];
      $path .= "/<path-to-your-utility-file>/utilities.php";
      include($path);

      try {
          $object = make_request('get', '/v1/payment_methods/pe_cajaarequipa_cash/required_fields');
          var_dump($object);
      } catch (Exception $e) {
          echo "Error: $e";
      }
      ?>
      ```
- - Python

    - ```
      from pprint import pprint

      from utilities import make_request

      payment_method = 'pe_cajaarequipa_cash'
      results = make_request(method='get',
                             path=f'/v1/payment_methods/{payment_method}/required_fields')
      pprint(results)
      ```

### Get Payment Method Required Fields Response

[Get Payment Required Fields](https://docs.rapyd.net/en/get-payment-method-required-fields.md "Get Payment Method Required Fields") describes the fields in the response.

- - Response

    - ```
      {
         "status": {
             "error_code": "",
             "status": "SUCCESS",
             "message": "",
             "response_code": "",
             "operation_id": "b7ea9de2-28b7-49a1-8b6c-dac900b257b7"
         },
         "data": {
             "type": "pe_cajaarequipa_cash",
             "fields": [
                 {
                     "name": "userubigeo",
                     "type": "string",
                     "regex": "",
                     "is_required": false,
                     "instructions": "6 digits which identify State, Province and District"
                 }
             ],
             "payment_method_options": [],
             "payment_options": [
                 {
                     "name": "customer",
                     "type": "customer",
                     "regex": "",
                     "description": "make sure a customer was created with first_name, last_name and email",
                     "is_required": true,
                     "is_updatable": false
                 },
                 {
                     "name": "description",
                     "type": "string",
                     "regex": "",
                     "description": "the description field must be filled in.",
                     "is_required": true,
                     "is_updatable": false
                 },
                 {
                     "name": "expiration",
                     "type": "string",
                     "regex": "^[0-9]{10}$",
                     "is_required": true
                 }
             ],
             "minimum_expiration_seconds": null,
             "maximum_expiration_seconds": null
         }
      }
         
      ```

### Process the Cash Payment

When your customer checks out on your website, use [Create Payment](https://docs.rapyd.net/en/create-payment.md "Create Payment") with the following parameters to get Rapyd to process your customer's bank payment:

Description of Body Parameters

| Body Parameter | Description |
| --- | --- |
| payment_method | Enter an object with the following field: `type` - **pe_cajaarequipa_cash** |
| amount | Enter **100** as the payment amount. |
| currency | Enter **PEN** as the currency code. |

### Create Payment Request

Request Rapyd to process your customer's payment (100 PEN in this case) as a cash transaction.

- - Request

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

      // Message body:
      {
         "amount": 100,
         "currency": "PEN",
         "payment_method": {
             "type": "pe_cajaarequipa_cash",
             "fields": {
             }
         }   
      }
      ```
- - .NET Core

    - ```

      using System;
      using System.Text.Json;

      namespace RapydApiRequestSample
      {
          class Program
          {
              static void Main(string[] args)
              {
                  try
                  {
                      var requestObj = new
                      {
                          amount = 100.00,
                          currency = "PEN",
                          payment_method = new
                          {
                              type = "pe_cajaarequipa_cash"
                          },
                      };

                      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);
                  }
              }
          }
      }
      ```
- - JavaScript

    - ```

      const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

      async function main() {
        try {
          const body = {
            amount: 100.00,
            currency: 'PEN',
            payment_method: {
              type: 'pe_cajaarequipa_cash'
            }
          };
          const result = await makeRequest('POST', '/v1/payments', body);

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

    - ```

      <?php
      $path = $_SERVER['DOCUMENT_ROOT'];
      $path .= "/<path-to-your-utility-file>/utilities.php";
      include($path);

      $body = [
          "amount" => "100.00",
          "currency" => "PEN",
          "payment_method" => [
              "type" => "pe_cajaarequipa_cash"
          ]
      ];

      try {
          $object = make_request('post', '/v1/payments', $body);
          var_dump($object);
      } catch (Exception $e) {
          echo "Error: $e";
      }
      ?>
      ```
- - Python

    - ```
      from pprint import pprint

      from utilities import make_request

      payment_body = {
          "amount": 100.00,
          "currency": "PEN",
          "payment_method": {
              "type": "pe_cajaarequipa_cash"
          }
      }

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

### Create Payment Response

[Create Payment](https://docs.rapyd.net/en/create-payment.md "Create Payment") describes the fields in the response.

- - Response

    - ```
      {
         "status": {
             "error_code": "",
             "status": "SUCCESS",
             "message": "",
             "response_code": "",
             "operation_id": "b046cb5a-0a90-44de-99b8-0ccdedb6ba73"
         },
         "data": {
             "id": "payment_ad5b69484bf8863c5e14df82ca4895d5",
             "amount": 0,
             "original_amount": 100,
             "is_partial": false,
             "currency_code": "PEN",
             "country_code": "pe",
             "status": "ACT",
             "description": "test",
             "merchant_reference_id": "",
             "customer_token": "cus_7c4d7860c6b2db1a40da55920f33cf7c",
             "payment_method": "other_0eefd99416330f37687ed153b8c72db2",
             "expiration": 0,
             "captured": true,
             "refunded": false,
             "refunded_amount": 0,
             "receipt_email": "",
             "redirect_url": "",
             "complete_payment_url": "",
             "error_payment_url": "",
             "receipt_number": "",
             "flow_type": "",
             "address": null,
             "statement_descriptor": "Rapyd",
             "transaction_id": "",
             "created_at": 1600963416,
             "metadata": {},
             "failure_code": "",
             "failure_message": "",
             "paid": false,
             "paid_at": 0,
             "dispute": null,
             "refunds": null,
             "order": null,
             "outcome": null,
             "visual_codes": {},
             "textual_codes": {
                 "TransactionID": "229845"
             },
             "instructions": [],
             "ewallet_id": "ewallet_be4ba8f13da40caa59a7e03022a8acfe",
             "ewallets": [
                 {
                     "ewallet_id": "ewallet_be4ba8f13da40caa59a7e03022a8acfe",
                     "amount": 100,
                     "percent": 100,
                     "refunded_amount": 0
                 }
             ],
             "payment_method_options": {},
             "payment_method_type": "pe_cajaarequipa_cash",
             "payment_method_type_category": "cash",
             "fx_rate": "",
             "merchant_requested_currency": null,
             "merchant_requested_amount": null,
             "fixed_side": "",
             "payment_fees": null,
             "invoice": "",
             "escrow": null,
             "group_payment": "",
             "initiation_type": "customer_present"
         }
      }
         
      ```

The `data` section of this response shows:

- The payment `id` is **payment_ad5b69484bf8863c5e14df82ca4895d5**. When you run this example in your own sandbox, you will get a different ID, which you will need for a later step.
- The `original_amount` is **100.00**.
- The `currency_code` is **PEN**.
- 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 **229845**. In this example, the payment code is a number in string format. Payment codes also can be bar codes or QR codes.
- Instructions for your customer to complete the payment.

Your website displays to your customer:

- the amount to pay
- the payment reference number
- the instructions for completing the payment.

### Close the Transaction

> **Note:**
>
> Simulating a Cash Payment
>
> The [sandbox](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_sandbox "Sandbox") does not directly simulate the action of the customer depositing cash at a point-of-sale location. You can simulate this action with the procedure described in [Complete Payment](https://docs.rapyd.net/en/complete-payment-363014.md "Complete Payment"). For this, you will need the payment ID that you generated in your sandbox.
>
> Configure your system to receive webhooks with the procedure described in [Defining a Webhook Endpoint](https://docs.rapyd.net/en/defining-a-webhook-endpoint.md "Defining a Webhook Endpoint").

After your customer successfully makes a payment:

1. The point-of-sale location informs Rapyd that the payment was completed successfully.
2. Rapyd sends you a webhook with the details of the completed transaction. See [Webhook - Payment Completed](https://docs.rapyd.net/en/payment-completed-webhook.md "Payment Completed Webhook") .

The webhook contains the same types of information as the response to the Create Payment request, except that the `status` (under `data`) now is **CLO** (closed). This shows that the transaction is complete.

At this point, you can display a (success) status on the screen to let your customer know that their purchase was successful and that they can go ahead and collect their purchased items.