Skip to main content

Documentation

Update Payment

Change or modify a payment when the status of the payment is ACT (active).

You can update additional fields if they are listed under payment_options in the response from Get Payment Method Required Fields and is_updatable is set to true.

This method triggers the Payment Updated Webhook. This webhook contains the same information as the response.

Parameters
Request Path Parameters

    • payment

    • ID of the payment. String starting with payment_.

Request Header Parameters
Request Body Parameters

    • description

    • Description of the payment transaction.

    • escrow

    • Determines whether the payment is held in escrow for later release.

      false

    • escrow_release_days

    • Determines the number of days after creation of the payment that funds are released from escrow. Funds are released at 5:00 pm GMT on the day indicated.

      Integer, range: 1-90.

      90

    • initiation_type

    • Indicates how the transaction was initiated. One of the following:

      • customer_present - The transaction was initiated by the customer.

      • installment - The transaction was initiated by a subscription where there is a fixed number of installments.

      • moto - The transaction was initiated by the merchant or Rapyd client for a mail order or telephone order.

        Note

        To enable moto in the production environment, contact Rapyd Client Support.

      • recurring - The transaction was initiated by a subscription where charges are made at regular intervals and there is no end date.

      • unscheduled - The transaction is a top-up transaction that was previously authorized by the cardholder and was initiated by the merchant or Rapyd client.

      customer_present

    • receipt_email

    • Email address that the receipt for this transaction is sent to.

Response Parameters
Code Samples

    • .NET

      • using System;
using System.Text.Json;

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

                var metadata = new
                {
                    merchant_defined = true
                };

                var address = new
                {
                    name = "John Doe",
                    line_1 = "123 Main Street",
                    line_2 = "Penthouse",
                    line_3 = "",
                    city = "Anytown",
                    state = "NY",
                    country = "US",
                    zip = "12345",
                    phone_number = "16125551234",
                    metadata,
                    canton = "",
                    district = "",
                };

                var requestObj = new
                {
                    receipt_email = "",
                    description = "",
                    address,
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", $"/v1/payments/{payment}", 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 = {
      receipt_email: '',
      description: '',
      address: {
        name: 'John Doe',
        line_1: '123 Main Street',
        line_2: 'Penthouse',
        line_3: '',
        city: 'Anytown',
        district: '',
        canton: '',
        state: 'NY',
        country: 'US',
        zip: '12345',
        phone_number: '16125551234',
        metadata: {
          merchant_defined: true
        }
      },
      canton: '',
      district: ''
    };
    const result = await makeRequest(
      'POST',
      '/v1/payments/payment_37d00f85277fa24e18a2ad67379e044c',
      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);
// Message body:

$body = [
    'receipt_email' => 'johndoe@rapyd.net'
];

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

    • Python

      • from pprint import pprint

from utilities import make_request

payment = "payment_35544ff0d05c578c87ad171f2dd2ba6e"
update_payment_body = {
    "description": "New Description"
}
response = make_request(method='post',
                        path=f'/v1/payments/{payment}',
                        body=update_payment_body)

pprint(response)

  • /v1/payments/:payment

  • Update Payment - address

  • curl -X post
https://sandboxapi.rapyd.net/v1/payments/payment_36724a4ea01b438fd24ac3ab00b29150
-H 'access_key: your-access-key-here'
-H 'Content-Type: application/json'
-H 'idempotency: your-idempotency-parameter-here'
-H 'salt: your-random-string-here'
-H 'signature: your-calculated-signature-here'
-H 'timestamp: your-unix-timestamp-here'
-d '{
	"receipt_email": "",
	"description": "",
	"address": {
		"name": "John Doe",
		"line_1": "123 Main Street",
		"line_2": "Penthouse",
		"line_3": "",
		"city": "Anytown",
		"state": "NY",
		"country": "US",
		"zip": "12345",
		"phone_number": "16125551234",
    "metadata": {
      "merchant_defined": "updates"
    },
		"canton": "",
		"district": ""
	}
}
'

  • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "b2993a91-0da0-43d2-9fe9-fd775550942d"
    },
    "data": {
        "id": "payment_36724a4ea01b438fd24ac3ab00b29150",
        "amount": 0,
        "original_amount": 45,
        "is_partial": false,
        "currency_code": "USD",
        "country_code": "US",
        "status": "ACT",
        "description": "Payment by customer's default payment method",
        "merchant_reference_id": "",
        "customer_token": "cus_e02329423b13bcd88a2c558fadfd1de9",
        "payment_method": "other_7f991f72a4c14c5cd79627ebc21241de",
        "payment_method_data": {
            "id": "other_7f991f72a4c14c5cd79627ebc21241de",
            "type": "us_stopngo_cash",
            "category": "cash",
            "metadata": {
                "merchant_defined": "Prime customer"
            },
            "image": "",
            "webhook_url": "",
            "supporting_documentation": "",
            "next_action": "not_applicable"
        },
        "auth_code": null,
        "expiration": 1664793479,
        "captured": true,
        "refunded": false,
        "refunded_amount": 0,
        "receipt_email": "",
        "redirect_url": "",
        "complete_payment_url": "",
        "error_payment_url": "",
        "receipt_number": "",
        "flow_type": "",
        "address": {
            "id": "address_aeb83a0148d246d7e1b256aedaba309f",
            "name": "John Doe",
            "line_1": "123 Main Street",
            "line_2": "Penthouse",
            "line_3": "",
            "city": "Anytown",
            "state": "NY",
            "country": "US",
            "zip": "12345",
            "phone_number": "16125551234",
            "metadata": {
                "merchant_defined": "updates"
            },
            "canton": "",
            "district": "",
            "created_at": 1663673557
        },
        "statement_descriptor": "Doc Team",
        "transaction_id": "",
        "created_at": 1663583879,
        "metadata": {},
        "failure_code": "",
        "failure_message": "",
        "paid": false,
        "paid_at": 0,
        "dispute": null,
        "refunds": null,
        "order": null,
        "outcome": null,
        "visual_codes": {},
        "textual_codes": {
            "code": "727536592440720524302165740782"
        },
        "instructions": [
            {
                "name": "instructions",
                "steps": [
                    {
                        "step1": "Please visit any one of your nearest participating Stop-N-Go stores.",
                        "step2": "Present your barcode to be scanned at the register and the exact $ amount for which the barcode was generated.",
                        "step3": "Provide cash to complete your payment.",
                        "step4": "Keep your receipt as proof of payment."
                    }
                ]
            }
        ],
        "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861",
        "ewallets": [
            {
                "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861",
                "amount": 45,
                "percent": 100,
                "refunded_amount": 0
            }
        ],
        "payment_method_options": {},
        "payment_method_type": "us_stopngo_cash",
        "payment_method_type_category": "cash",
        "fx_rate": 1,
        "merchant_requested_currency": null,
        "merchant_requested_amount": null,
        "fixed_side": "",
        "payment_fees": null,
        "invoice": "",
        "escrow": null,
        "group_payment": "",
        "cancel_reason": null,
        "initiation_type": "customer_present",
        "mid": "",
        "next_action": "pending_confirmation",
        "error_code": "",
        "remitter_information": {}
    }
}

  • Update Payment - Cancel Escrow

  • curl -X post
https://sandboxapi.rapyd.net/v1/payments/payment_36724a4ea01b438fd24ac3ab00b29150
-H 'access_key: your-access-key-here'
-H 'Content-Type: application/json'
-H 'idempotency: your-idempotency-parameter-here'
-H 'salt: your-random-string-here'
-H 'signature: your-calculated-signature-here'
-H 'timestamp: your-unix-timestamp-here'
-d '{
   "escrow": false  
}
'
  • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "7da28ae8-b18e-451c-bf5a-c1c244c9c3d8"
    },
    "data": {
        "id": "payment_144ed1ab89c5996b15d49655701700b3",
        "amount": 12008,
        "original_amount": 12008,
        "is_partial": false,
        "currency_code": "MXN",
        "country_code": "MX",
        "status": "CLO",
        "description": "",
        "merchant_reference_id": "",
        "customer_token": "cus_2e2809d2fcf8911272e980e9522397ec",
        "payment_method": "other_82894fd9f8056d28fa9d84533c8befca",
        "payment_method_data": {
            "id": "other_82894fd9f8056d28fa9d84533c8befca",
            "type": "mx_banorte_bank",
            "category": "bank_redirect",
            "metadata": {},
            "image": "",
            "webhook_url": "",
            "supporting_documentation": "",
            "next_action": "not_applicable",
            "bic_swift": "",
            "account_last4": ""
        },
        "auth_code": null,
        "expiration": 1676292967,
        "captured": true,
        "refunded": false,
        "refunded_amount": 0,
        "receipt_email": "",
        "redirect_url": "https://sandboxcheckout.rapyd.net/complete-bank-payment?token=payment_144ed1ab89c5996b15d49655701700b3&complete_payment_url=https%3A%2F%2Fcomplete.example.net&error_payment_url=https%3A%2F%2Ferror.example.net",
        "complete_payment_url": "https://complete.example.net",
        "error_payment_url": "https://error.example.net",
        "receipt_number": "",
        "flow_type": "",
        "address": null,
        "statement_descriptor": "Doc Team",
        "transaction_id": "",
        "created_at": 1675083367,
        "metadata": {},
        "failure_code": "",
        "failure_message": "",
        "paid": true,
        "paid_at": 1675083407,
        "dispute": null,
        "refunds": null,
        "order": null,
        "outcome": null,
        "visual_codes": {},
        "textual_codes": {},
        "instructions": [
            {
                "name": "instructions",
                "steps": [
                    {
                        "step1": "You will be redirected to a bank payment page to complete the payment"
                    }
                ]
            }
        ],
        "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861",
        "ewallets": [
            {
                "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861",
                "amount": 12008,
                "percent": 100,
                "released_amount": 12008,
                "refunded_amount": 0
            }
        ],
        "payment_method_options": {},
        "payment_method_type": "mx_banorte_bank",
        "payment_method_type_category": "bank_redirect",
        "fx_rate": 1,
        "merchant_requested_currency": null,
        "merchant_requested_amount": null,
        "fixed_side": "",
        "payment_fees": null,
        "invoice": "",
        "escrow": {
            "id": "escrow_22409bf1834b8204a0c29bb0edd21ed0",
            "payment": "payment_144ed1ab89c5996b15d49655701700b3",
            "currency": "MXN",
            "amount_on_hold": 0,
            "total_amount_released": 12008,
            "status": "canceled",
            "escrow_release_days": null,
            "created_at": 1675083367,
            "updated_at": 1675083434,
            "last_payment_completion": 1675083407
        },
        "group_payment": "",
        "cancel_reason": null,
        "initiation_type": "customer_present",
        "mid": "",
        "next_action": "not_applicable",
        "error_code": "",
        "remitter_information": {}
    }
}
In this section:

The number of seconds elapsed since the beginning of the Unix epoch, which was 00:00:00 GMT on January 1, 1970. 10-digit integer.

A number for a bank account that is used for international transfers.

A server used by issuing banks to authenticate card users by 3DS authentication.

For card transactions, a service that checks whether the cardholder's billing address matches the address for the cardholder's account.

An alphanumeric identifier for financial institutions, also known informally as a SWIFT code or SWIFT/BIC code.

A numeric identifier for financial institutions. It appears as the first four to six digits on a payment card.

A unique number for a payment card, usually 14 to 19 digits in length. Also known as a card number, payment card number or funding primary account number (FPAN).

A numeric code printed on the card, consisting of 3 or 4 digits. Use of the code indicates that the person making the transaction has access to the physical card. This value cannot be stored in any way. Also known as CCV, CID, CSC and CVC.

A protocol that provides increased security for card-not-present transactions. Rapyd supports version 2.2.