Skip to main content

Documentation

Canceling a Payment

Stop a payment before it has been completed.

Rapyd provides a quick and easy method for you to cancel payments before they are completed. Canceling a payment is relevant to payment methods such as cash, bank transfers, and online bank redirects, as described in the following use cases:

This use case applies to payment methods where is_cancelable = true in the response to List Payment Methods by Country.

If is_cancelable = false or the payment is already completed, make a refund instead. A use case that describes that scenario is Refunds.

Canceling a Payment 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.

This workflow describes an item bought on your website for 555.99 PHP (Philippine Pesos) through a bank redirect, and then canceled before completed.

Step 1: Customer Cancels Bank Redirect
customer-cancel-bank.jpg

  1. Customer selects online bank payment in the created checkout.

  2. Receive a one-time bank website URL where you redirect your customer for completing the payment.

  3. The customer goes to the redirected bank URL but decided to cancel.

Step 2: Process the Cancellation
process-cancel.jpg

  1. Your website back end requests from Rapyd to cancel the customer's payment.

  2. Rapyd processes the cancellation and notifies you that it was successful.

  3. You display a confirmation to the customer.

How Canceling a Payment Works
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.

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

Description of Query Parameters

Query Parameter

Description

country

Enter PH as the country code for the Philippines.

currency

Enter PHP as the currency code for Philippine pesos.

List Payment Methods by Country Request

You ask for the list of all available payment methods in PHP (Philippine Pesos).

    • Request

      • // Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/country?country=PH&currency=PHP

// Message body absent

    • .NET Core

      • using System;

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

                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('../../../../../Utilities/JS/utilities').makeRequest;

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

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

    • PHP

      • <?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/code_race_2020/Utilities/PHP/utilities.php";
include($path);

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

    • Python

      • from pprint import pprint

from utilities import make_request

country = 'PH'
currency = 'PHP'
results = make_request(method='get',
                       path=f'/v1/payment_methods/country?country={country}&currency={currency}')
pprint(results)
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": "6e17b56c-e3cf-40dd-abc5-80b3688d05e8"
    },
    "data": [{
            "type": "ph_bancnet_bank",
            "name": "Bancnet Online Payments Philippines",
            "category": "bank_redirect",
            "image": "",
            "country": "ph",
            "payment_flow_type": "redirect_url",
            "currencies": [
                "PHP"
            ],
            "status": 1,
            "is_cancelable": true,
            "payment_options": [{
                    "name": "description",
                    "type": "string",
                    "regex": "",
                    "description": "the description field must be filled in.",
                    "is_required": true,
                    "is_updatable": false
                }
            ],
            "is_expirable": false,
            "is_online": false,
            "minimum_expiration_seconds": null,
            "maximum_expiration_seconds": null
        }
    ]
}

The data section of this response shows:

  • ph_bancnet_bank is an acceptable payment method in the bank_redirect category.

  • The value of is_cancelable is true.

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 ph_bancnet_bank as the payment method type.

Get Payment Method Required Fields Request

You ask for the set of required fields for a ph_bancnet_bank payment.

    • Request

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

// Message body absent

    • .NET Core

      • using System;

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

                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('../../../../../Utilities/JS/utilities').makeRequest;

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

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

    • PHP

      • <?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/code_race_2020/Utilities/PHP/utilities.php";
include($path);

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

    • Python

      • from pprint import pprint

from utilities import make_request

payment_method = 'ph_bancnet_bank'
results = make_request(method='get',
                       path=f'/v1/payment_methods/{payment_method}/required_fields')
pprint(results)
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": "7cb8b5ad-c445-4009-8d27-a9550656ff56"
    },
    "data": {
        "type": "ph_bancnet_bank",
        "fields": [],
        "payment_method_options": [],
        "payment_options": [
            {
                "name": "description",
                "type": "string",
                "regex": "",
                "description": "the description field must be filled in.",
                "is_required": true,
                "is_updatable": false
            }
        ],
        "minimum_expiration_seconds": null,
        "maximum_expiration_seconds": null
    }
}

The data section of this response shows that a description field is required for a ph_bancnet_bank payment.

Creating the Payment

When your customer checks out on your website, you ask Rapyd to process his bank payment.

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

Description of Body Parameters

Body Parameter

Description

amount

Enter 555.99 as the payment amount.

currency

Enter PHP as the currency code for Philippine pesos.

description

Enter Online bank payment.

complete_payment_url

Replace the https://success_example.net example with your real website URL where you want the bank to redirect the customer if the payment succeeds.

error_payment_url

Replace the https://error_example.net example with your real website URL where you want the bank to redirect the customer if the payment fails.

payment_method

Enter an object with the following field: type - ph_bancnet_bank

Create Payment Request

You ask Rapyd to process the customer's 555.99 PHP (Philippine Pesos) payment as a redirected bank payment.

    • Request

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

// Message body:
{
    "amount": 555.99,
    "currency": "PHP",
    "description": "Online bank payment",
    "complete_payment_url": "https://success_example.net",
    "error_payment_url": "https://error_example.net",
    "payment_method": {
        "type": "ph_bancnet_bank"
    }
}

    • .NET Core

      • using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                var requestObj = new
                {
                    amount = 555.99,
                    currency = "PHP",
                    description = "Online bank payment",
                    complete_payment_url = "https:success_example.net",
                    error_payment_url = "https:error_example.net",
                    payment_method = new {
                        type = "ph_bancnet_bank",
                    }
                };

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

    • PHP

      • <?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/code_race_2020/Utilities/PHP/utilities.php";
include($path);

$body = [
    "amount" => "555.99",
    "currency" => "PHP",
    "description" => "Online bank payment",
    "complete_payment_url" => "https://success_example.net",
    "error_payment_url" => "https://error_example.net",
    "payment_method" => [
        "type" => "ph_bancnet_bank"
    ]
];

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": 555.99,
    "currency": "PHP",
    "description": "Online bank payment",
    "complete_payment_url": "https://success_example.net",
    "error_payment_url": "https://error_example.net",
    "payment_method": {
        "type": "ph_bancnet_bank"
    }
}

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

Let's take a look at the response.

    • Response

      • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "afc7c939-35d7-41d7-bfe7-a4166a4afd26"
    },
    "data": {
        "id": "payment_1b24b2d6cde2fc949e68dd43672e6194",
        "amount": 0,
        "original_amount": 555.99,

        //     ...

        "currency_code": "PHP",
        "country_code": "ph",
        "status": "ACT",
        "description": "Online bank payment",

        //     ...

        "customer_token": "cus_b16c679b8f4adc19e9bae0c17b4ae9ce",
        "payment_method": "other_e834a5e5f5de12fa98ea08d1be874919",

        //     ...

        "redirect_url": "https://sandbox.rapyd.net/complete-bank-payment?token=payment_1b24b2d6cde2fc949e68dd43672e6194&complete_payment_url=https://success_example.net&error_payment_url=https://error_example.net",
        "complete_payment_url": "https://success_example.net",
        "error_payment_url": "https://error_example.net",

        //     ...

        "paid": false,

        //     ...

        "payment_method_type": "ph_bancnet_bank",
        "payment_method_type_category": "bank_redirect",

        //     ...

    }
}

The data section of this response shows:

  • The payment id is payment_1b24b2d6cde2fc949e68dd43672e6194. 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 555.99.

  • The currency_code is PHP (Philippine Pesos).

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

  • These URLs are included:

    • redirect_url - You redirect your customer to this one-time bank website URL to complete the payment.

    • complete_payment_url and error_payment_url - Rapyd provides these URLs to the bank to redirect the customer back to your website depending on whether the purchase succeeded.

  • The value of paid is false since the customer did complete the payment.

Your website redirects the customer to the bank website to complete the payment, but the customer decides to cancel the purchase.

Canceling the Payment

When your user requests cancellation of the purchase, you ask Rapyd to process the cancellation.

For that, you'll use Cancel Payment with the following parameter:

Description of Path Parameters

Path Parameter

Description

payment

Enter the id value that you received when you created the incomplete payment in your sandbox. Our example uses the payment ID we received in our sandbox: payment_1b24b2d6cde2fc949e68dd43672e6194

Cancel Payment Request

You ask Rapyd to process the cancellation.

    • Request

      • // Request URL: DELETE https://sandboxapi.rapyd.net/v1/payments/payment_1b24b2d6cde2fc949e68dd43672e6194

// Message body absent

    • .NET Core

      • using System;

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

                string result = RapydApiRequestSample.Utilities.MakeRequest("DELETE", $"/v1/payments/{payment}");

                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 result = await makeRequest(
      'DELETE',
      '/v1/payments/payment_1b24b2d6cde2fc949e68dd43672e6194'
    );

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

    • PHP

      • <?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/code_race_2020/Utilities/PHP/utilities.php";
include($path);

try {
    $object = make_request('delete', '/v1/payments/payment_1b24b2d6cde2fc949e68dd43672e6194');
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>
Cancel Payment Response

Let's take a look at the response.

    • Response

      • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "e4c3ef95-d698-42ef-9284-568eefd17986"
    },
    "data": {
        "id": "payment_1b24b2d6cde2fc949e68dd43672e6194",
        "amount": 0,
        "original_amount": 555.99,

        //              ...

        "currency_code": "PHP",
        "country_code": "ph",
        "status": "CAN",
        "description": "Online bank payment",

        //              ...

        "customer_token": "cus_b16c679b8f4adc19e9bae0c17b4ae9ce",
        "payment_method": "other_e834a5e5f5de12fa98ea08d1be874919",

        //              ...

        "paid": false,

        //              ...

        "payment_method_type": "ph_bancnet_bank",
        "payment_method_type_category": "bank_redirect",

        //              ...

    }
}

The data section of this response shows:

  • The original_amount is 555.99.

  • The status is CAN (Canceled). This means that the cancellation process is complete.

  • The value of paid is false since the original transaction was not paid.

Your website shows your customer a confirmation that the cancellation is complete.

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: