Post

/v3/payment_requests/{payment_request_id}/cancel

Cancel a payment request that was created. End users would not be able to make payments after cancellation. Updates cannot be made for PAY or PAY_AND_SAVE once the payment request has been processed. This feature is subjected to availability by the payment provider.

Security

HTTP

Type basic

Header parameters

api-version

string

Valid values[ "2024-11-11" ]

Path parameters

payment_request_id

stringRequired

Min length39

Max length39

Examplepr-8877c08a-740d-4153-9816-3d744ed197a5

Responses

200

Cancel a Payment Request

cancelPaymentResponseRedirect

{
  "business_id": "5f27a14a9bf05c73dd040bc8",
  "reference_id": "90392f42-d98a-49ef-a7f3-abcezas123",
  "payment_request_id": "pr-90392f42-d98a-49ef-a7f3-abcezas123",
  "customer_id": "cust-90392f42-d98a-49ef-a7f3-abcezas123",
  "type": "PAY",
  "country": "ID",
  "currency": "IDR",
  "request_amount": 10000.01,
  "capture_method": "AUTOMATIC",
  "channel_code": "DANA",
  "channel_properties": {
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "actions": [
    {
      "type": "REDIRECT_CUSTOMER",
      "value": "xendit.co/example",
      "descriptor": "WEB_URL"
    }
  ],
  "status": "CANCELED",
  "description": "Description examples",
  "metadata": {
    "metametadata": "metametametadata"
  },
  "shipping_information": {
    "city": "Singapore",
    "country": "SG",
    "postal_code": "644228",
    "street_line1": "Merlion Bay Sands Suites",
    "street_line2": "21-37",
    "province_state": "Singapore"
  },
  "items": [
    {
      "type": "PHYSICAL_PRODUCT",
      "name": "Vyson Dacuum Cleaner",
      "net_unit_amount": 10000.01,
      "quantity": 1
    }
  ],
  "created": "2021-12-31T23:59:59Z",
  "updated": "2021-12-31T23:59:59Z"
}

cancelPaymentResponsePresentToCustomer

{
  "business_id": "5f27a14a9bf05c73dd040bc8",
  "reference_id": "90392f42-d98a-49ef-a7f3-abcezas123",
  "payment_request_id": "pr-90392f42-d98a-49ef-a7f3-abcezas123",
  "customer_id": "cust-90392f42-d98a-49ef-a7f3-abcezas123",
  "type": "REUSABLE_PAYMENT_CODE",
  "country": "ID",
  "currency": "IDR",
  "request_amount": 10000.01,
  "capture_method": "AUTOMATIC",
  "channel_code": "BRI_VIRTUAL_ACCOUNT",
  "channel_properties": {
    "expires_at": "2024-12-31T23:59:59Z"
  },
  "actions": [
    {
      "type": "PRESENT_TO_CUSTOMER",
      "descriptor": "VIRTUAL_ACCOUNT_NUMBER",
      "value": "1251255"
    }
  ],
  "status": "CANCELED",
  "description": "Description examples",
  "metadata": {
    "metametadata": "metametametadata"
  },
  "shipping_information": {
    "city": "Singapore",
    "country": "SG",
    "postal_code": "644228",
    "street_line1": "Merlion Bay Sands Suites",
    "street_line2": "21-37",
    "province_state": "Singapore"
  },
  "items": [
    {
      "type": "PHYSICAL_PRODUCT",
      "name": "Vyson Dacuum Cleaner",
      "net_unit_amount": 10000.01,
      "quantity": 1
    }
  ],
  "created": "2021-12-31T23:59:59Z",
  "updated": "2021-12-31T23:59:59Z"
}

Expand All

object

Payment request object

business_id

string

Xendit-generated identifier for the business that owns the transaction

Example5f27a14a9bf05c73dd040bc8

reference_id

string

A reference ID from merchants to identify their request. For "CARDS" channel code, reference ID must be unique.

Min length1

Max length255

payment_request_id

string

Xendit unique Payment Request ID generated as reference after creation of payment request.

Examplepr-1102feb0-bb79-47ae-9d1e-e69394d3949c

payment_token_id

string

Xendit unique Payment Token ID generated as reference for reusable payment details of the end user.

Examplept-cc3938dc-c2a5-43c4-89d7-7570793348c2

customer_id

string

Xendit unique Capture ID generated as reference for the end user

Max length41

Examplecust-b98d6f63-d240-44ec-9bd5-aa42954c4f48

latest_payment_id

string

Latest Payment ID linked to the payment request.

Examplepy-1402feb0-bb79-47ae-9d1e-e69394d3949c

type

string

The payment collection intent type for the payment request.

PAY: Create a payment request that is able to receive one payment.

PAY_AND_SAVE: Create a payment request that is able to receive one payment. If the payment is successful, a reusable payment token will be returned for subsequent payment requests.

REUSABLE_PAYMENT_CODE: Create a payment request that is able to receive multiple payments. This is only used for repeat use payment method like a static QR, a predefined OTC payment code or a predefined Virtual Account number.

Valid values[ "PAY", "PAY_AND_SAVE", "REUSABLE_PAYMENT_CODE" ]

country

string

ISO 3166-1 alpha-2 two-letter country code for the country of transaction.

Valid values[ "ID", "PH", "VN", "TH", "SG", "MY" ]

ExampleID

currency

string

ISO 4217 three-letter currency code for the payment.

Valid values[ "IDR", "PHP", "VND", "THB", "SGD", "MYR", "USD" ]

ExampleIDR

request_amount

number

The intended payment amount to be collected from the end user.

Minimum0.0

Example10000

capture_method

string

AUTOMATIC: payment capture will be processed immediately after payment request is created. MANUAL: payment capture requires merchant's trigger via payment capture endpoint before being processed

Valid values[ "AUTOMATIC", "MANUAL" ]

Default"AUTOMATIC"

ExampleAUTOMATIC

channel_code

string

Channel code used to select the payment method provider. Use routing payment channels mapping for full list of channel codes.

channel_properties

object (Payments_API_ChannelProperties)

Data required to initiate transaction with payment method provider. Use routing payment channels mapping for full list of data required.

actions

Array of object (Payments_API_Actions)

object

Actions object contains possible next steps merchants can take to proceed with payment collection from end user

type

The type of action that merchant system will need to handle to complete payment.

Valid values[ "PRESENT_TO_CUSTOMER", "REDIRECT_CUSTOMER", "API_POST_REQUEST" ]

descriptor

The type of action that merchant system will need to handle to complete payment.

Valid values[ "CAPTURE_PAYMENT", "PAYMENT_CODE", "QR_STRING", "VIRTUAL_ACCOUNT_NUMBER", "WEB_URL", "DEEPLINK_URL", "VALIDATE_OTP", "RESEND_OTP" ]

value

string

The specific value that will be used by merchant to complete the action

status

string

Status of the payment request.

Valid values[ "ACCEPTING_PAYMENTS", "REQUIRES_ACTION", "AUTHORIZED", "CANCELED", "EXPIRED", "SUCCEEDED", "FAILED" ]

ExampleSUCCEEDED

failure_code

string

Failure codes for payments.

Valid values[ "ACCOUNT_ACCESS_BLOCKED", "INVALID_MERCHANT_SETTINGS", "INVALID_ACCOUNT_DETAILS", "PAYMENT_ATTEMPT_COUNTS_EXCEEDED", "USER_DEVICE_UNREACHABLE", "CHANNEL_UNAVAILABLE", "INSUFFICIENT_BALANCE", "ACCOUNT_NOT_ACTIVATED", "INVALID_TOKEN", "SERVER_ERROR", "PARTNER_TIMEOUT_ERROR", "TIMEOUT_ERROR", "USER_DECLINED_PAYMENT", "USER_DID_NOT_AUTHORIZE", "PAYMENT_REQUEST_EXPIRED", "FAILURE_DETAILS_UNAVAILABLE", "EXPIRED_OTP", "INVALID_OTP", "PAYMENT_AMOUNT_LIMITS_EXCEEDED", "OTP_ATTEMPT_COUNTS_EXCEEDED", "CARD_DECLINED", "DECLINED_BY_ISSUER", "ISSUER_UNAVAILABLE", "INVALID_CVV", "DECLINED_BY_PROCESSOR", "CAPTURE_AMOUNT_EXCEEDED ", "AUTHENTICATION_FAILED" ]

ExampleCARD_DECLINED

description

string

A custom description for the Payment Request.

Min length1

Max length1000

ExamplePayment for your order #123

metadata

object (Payments_API_MerchantMetadata)

Key-value entries for your custom data. You can specify up to 50 keys, with key names up to 40 characters and values up to 500 characters. This is for your convenience. Xendit will not use this data for any processing.

Example{ "my_custom_id": "merchant-123", "my_custom_order_id": "order-123" }

items

Array of object (Payments_API_XenditStandardItem)

Array of objects describing the item/s attached to the payment.

object

type

Type of item

Valid values[ "DIGITAL_PRODUCTS", "PHYSICAL_PRODUCT", "DIGITAL_SERVICE", "PHYSICAL_SERVICE", "FEES", "DISCOUNT" ]

name

string

Name of item

Min length1

Max length255

net_unit_amount

number

Net amount to be charged per unit. Must be a negative number when type = DISCOUNT

quantity

integer

Number of units of this item in the basket

Minimum1.0

url

string

URL of the item. Must be HTTPS or HTTP

image_url

string

URL of the image of the item. Must be HTTPS or HTTP

category

string

Category for item

Max length255

subcategory

string

Sub-category for item

Max length255

description

string

Description of item

Max length255

metadata

object (Payments_API_MerchantMetadata)

Key-value entries for your custom data. You can specify up to 50 keys, with key names up to 40 characters and values up to 500 characters. This is for your convenience. Xendit will not use this data for any processing.

Example{ "my_custom_id": "merchant-123", "my_custom_order_id": "order-123" }

shipping_information

object (Payments_API_XenditStandardShippingInformation)

country

2-letter ISO 3166-2 country code for the customer’s shipping country

Valid values[ "ID", "PH", "VN", "TH", "SG", "MY" ]

street_line1

string

Building name and apartment unit number

Min length1

Max length255

street_line2

string

Building street address

Min length1

Max length255

city

string

City, village or town as appropriate

Min length1

Max length255

province_state

string

Either one of (whichever is applicable): Geographic area, province, or region / Formal state designation within country

Min length1

Max length255

postal_code

string

Postal, zip or rural delivery code, if applicable

Min length1

Max length255

created

string (date-time)

ISO 8601 date-time format.

Example2021-12-31T23:59:59Z

updated

string (date-time)

ISO 8601 date-time format.

Example2021-12-31T23:59:59Z

400

Bad request

OneOf

Payments_API_Http400InactivePaymentRequest

object (Payments_API_Http400InactivePaymentRequest)

error_code

string

Valid values[ "INACTIVE_PAYMENT_REQUEST" ]

message

string

Payment request is already inactive.

Payments_API_Http400ApiValidationError

object (Payments_API_Http400ApiValidationError)

error_code

string

Valid values[ "API_VALIDATION_ERROR" ]

message

string

Fields or values in the payment request does not comply with our API specification. Check the specific error message for debugging.

Payments_API_Http400TemporarilyUnavailable

object (Payments_API_Http400TemporarilyUnavailable)

error_code

string

Valid values[ "TEMPORARILY_UNAVAILABLE" ]

message

string

Requested feature is unavailable during this timing.

Payments_API_Http400IneligibleTransactionStatus

object (Payments_API_Http400IneligibleTransactionStatus)

error_code

string

Valid values[ "INELIGIBLE_TRANSACTION_STATUS" ]

message

string

Feature is not allowed for the payment request because of its current status. Check the specific error message for debugging.

404

Not found

OneOf

Payments_API_Http404DataNotFound

object (Payments_API_Http404DataNotFound)

error_code

string

Valid values[ "DATA_NOT_FOUND" ]

message

string

ID specified in request cannot be found.

500

Internal server error

OneOf

Payments_API_Http500ServerError

object (Payments_API_Http500ServerError)

error_code

string

Valid values[ "SERVER_ERROR" ]

message

string

An unexpected error occured, our team has been notified and will troubleshoot the issue

503

Service unavailable

OneOf

Payments_API_Http503ChannelUnavailable

object (Payments_API_Http503ChannelUnavailable)

error_code

string

Valid values[ "CHANNEL_UNAVAILABLE" ]

message

string

The channel requested is currently experiencing unexpected issues. The provider will be notified to resolve this issue.