Cancel Payment (two cards)

POST

payments

{payment_id}

transactions

{transaction_id}

cancel

Cancel Payment (two cards)

curl --request POST \
  --url https://api-sandbox.y.uno/v2/payments/{payment_id}/transactions/{transaction_id}/cancel \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "merchant_reference": "<string>",
  "description": "<string>"
}
'

import requests

url = "https://api-sandbox.y.uno/v2/payments/{payment_id}/transactions/{transaction_id}/cancel"

payload = {
    "merchant_reference": "<string>",
    "description": "<string>"
}
headers = {
    "X-Idempotency-Key": "<x-idempotency-key>",
    "public-api-key": "<api-key>",
    "private-secret-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': '<x-idempotency-key>',
    'public-api-key': '<api-key>',
    'private-secret-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({merchant_reference: '<string>', description: '<string>'})
};

fetch('https://api-sandbox.y.uno/v2/payments/{payment_id}/transactions/{transaction_id}/cancel', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.y.uno/v2/payments/{payment_id}/transactions/{transaction_id}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'merchant_reference' => '<string>',
    'description' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Idempotency-Key: <x-idempotency-key>",
    "private-secret-key: <api-key>",
    "public-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.y.uno/v2/payments/{payment_id}/transactions/{transaction_id}/cancel"

	payload := strings.NewReader("{\n  \"merchant_reference\": \"<string>\",\n  \"description\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
	req.Header.Add("public-api-key", "<api-key>")
	req.Header.Add("private-secret-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.y.uno/v2/payments/{payment_id}/transactions/{transaction_id}/cancel")
  .header("X-Idempotency-Key", "<x-idempotency-key>")
  .header("public-api-key", "<api-key>")
  .header("private-secret-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchant_reference\": \"<string>\",\n  \"description\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.y.uno/v2/payments/{payment_id}/transactions/{transaction_id}/cancel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["public-api-key"] = '<api-key>'
request["private-secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchant_reference\": \"<string>\",\n  \"description\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "7c1b6e2a-5f3d-4a8e-9b21-3e4f5a6b7c8d",
  "account_id": "493e9374-510a-4201-9e09-de669d75f256",
  "description": "Order paid with two cards",
  "country": "BR",
  "status": "CANCELED",
  "sub_status": "CANCELED",
  "merchant_order_id": "order-10045",
  "created_at": "2026-10-27T14:02:11.120Z",
  "updated_at": "2026-10-27T14:02:12.300Z",
  "split_payment_methods": true,
  "payment_methods_count": 2,
  "sdk_action_required": false,
  "amount": {
    "currency": "BRL",
    "value": 300
  },
  "checkout": {
    "session": null
  },
  "payment_method": {
    "capture": false,
    "account_updater": false,
    "payment_methods": [
      {
        "sequence": 1,
        "type": "CARD",
        "amount": {
          "currency": "BRL",
          "value": 200
        },
        "transactions": [
          {
            "id": "d2a4f6b8-1c3e-4a5b-8d7f-9e0a1b2c3d4e",
            "type": "AUTHORIZE",
            "status": "SUCCEEDED",
            "category": "CARD",
            "amount": 200,
            "provider_id": "YUNO_TEST_PAYMENT_GATEWAY",
            "response_code": "SUCCEEDED",
            "response_message": "Transaction successful",
            "reason": null,
            "description": null,
            "merchant_reference": null,
            "three_d_secure_action_required": false,
            "created_at": "2026-10-27T14:02:11.402Z",
            "updated_at": "2026-10-27T14:02:12.118Z"
          },
          {
            "id": "c7f9e1a3-6b8d-4f0a-9c2e-4d5e6f7a8b9c",
            "type": "CANCEL",
            "status": "SUCCEEDED",
            "category": "CARD",
            "amount": 200,
            "provider_id": "YUNO_TEST_PAYMENT_GATEWAY",
            "response_code": "SUCCEEDED",
            "response_message": "Transaction successful",
            "reason": null,
            "description": null,
            "merchant_reference": null,
            "three_d_secure_action_required": false,
            "created_at": "2026-10-27T14:02:11.402Z",
            "updated_at": "2026-10-27T14:02:12.118Z"
          }
        ]
      },
      {
        "sequence": 2,
        "type": "CARD",
        "amount": {
          "currency": "BRL",
          "value": 100
        },
        "transactions": [
          {
            "id": "e3b5a7c9-2d4f-4b6c-9e8a-0f1b2c3d4e5f",
            "type": "AUTHORIZE",
            "status": "SUCCEEDED",
            "category": "CARD",
            "amount": 100,
            "provider_id": "YUNO_TEST_PAYMENT_GATEWAY",
            "response_code": "SUCCEEDED",
            "response_message": "Transaction successful",
            "reason": null,
            "description": null,
            "merchant_reference": null,
            "three_d_secure_action_required": false,
            "created_at": "2026-10-27T14:02:11.402Z",
            "updated_at": "2026-10-27T14:02:12.118Z"
          }
        ]
      }
    ]
  },
  "customer_payer": {
    "id": "cfae0941-7234-427a-a739-ef4fce966c79",
    "first_name": "Ana",
    "last_name": "Souza",
    "email": "ana.souza@example.com"
  },
  "workflow": "DIRECT",
  "callback_url": "https://merchant.example.com/checkout/return",
  "metadata": []
}

{
  "code": "INVALID_PARAMETERS",
  "messages": [
    "The header 'x-idempotency-key' is required."
  ]
}

{
  "code": "INVALID_CREDENTIALS",
  "messages": [
    "Invalid credentials"
  ]
}

This request cancels one authorized card of a payment created with Create Payment (two cards). Cancel is per card: send the id of that card’s AUTHORIZE transaction from payment_method.payment_methods[].transactions. To cancel the whole payment in one request, use Cancel or Refund a Payment (two cards). The response is 201 with the payment in the v2 shape.

While the payment is in REFUND_RETRY_IN_PROCESS or CANCEL_RETRY_IN_PROCESS, a cancel is rejected. See Pay with two cards.

This request requires an X-Idempotency-Key. See Authentication for details.

Authorizations

public-api-key

string

header

default:<Your public-api-key>

required

private-secret-key

string

header

default:<Your private-secret-key>

required

Headers

X-Idempotency-Key

string<uuid>

required

Unique key for this request. Required on every v2 payment request. Retry an unclear outcome with the same key. Without it the request is rejected with 400 INVALID_PARAMETERS: "The header 'x-idempotency-key' is required."

Path Parameters

payment_id

string<uuid>

required

The id of the payment returned by POST /v2/payments.

transaction_id

string<uuid>

required

The id of the card transaction to operate on, from payment_method.payment_methods[].transactions[].

Body

application/json

merchant_reference

string

required

Identification of the payment transaction defined by the merchant (MAX 255; MIN 3).

description

string

Description of the cancellation.(MAX 255; MIN 3)

reason

enum<string>

Reason for the operation. Possible values are DUPLICATE, FRAUDULENT and REQUESTED_BY_CUSTOMER.

Available options:

DUPLICATE,

FRAUDULENT,

REQUESTED_BY_CUSTOMER

Response

The payment after the operation, in the v2 shape

A payment funded by two cards.

string<uuid>

account_id

string<uuid>

description

string

country

string

status

string

Aggregated status of the payment. See Pay with two cards.

sub_status

string

Aggregated sub status, for example APPROVED, AUTHORIZED, PARTIALLY_CAPTURED, PARTIALLY_REFUNDED, REFUND_RETRY_IN_PROCESS or CANCEL_RETRY_IN_PROCESS.

merchant_order_id

string

merchant_reference

string

created_at

string<date-time>

updated_at

string<date-time>

split_payment_methods

boolean

true for a payment funded by two cards.

payment_methods_count

integer

Number of cards that fund the payment: 2.

sdk_action_required

boolean

true when the SDK must continue the payment, for example to run a 3DS challenge.

amount

object

Total of the payment.

Show child attributes

checkout

object

Show child attributes

payment_method

object

Show child attributes

customer_payer

object

The payer, as sent in the request.

additional_data

object | null

callback_url

string

workflow

enum<string>

Available options:

DIRECT,

REDIRECT,

SDK_CHECKOUT

metadata

object[]

⌘I

Cancel Payment (two cards)

curl --request POST \
  --url https://api-sandbox.y.uno/v2/payments/{payment_id}/transactions/{transaction_id}/cancel \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "merchant_reference": "<string>",
  "description": "<string>"
}
'

import requests

url = "https://api-sandbox.y.uno/v2/payments/{payment_id}/transactions/{transaction_id}/cancel"

payload = {
    "merchant_reference": "<string>",
    "description": "<string>"
}
headers = {
    "X-Idempotency-Key": "<x-idempotency-key>",
    "public-api-key": "<api-key>",
    "private-secret-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': '<x-idempotency-key>',
    'public-api-key': '<api-key>',
    'private-secret-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({merchant_reference: '<string>', description: '<string>'})
};

fetch('https://api-sandbox.y.uno/v2/payments/{payment_id}/transactions/{transaction_id}/cancel', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.y.uno/v2/payments/{payment_id}/transactions/{transaction_id}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'merchant_reference' => '<string>',
    'description' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Idempotency-Key: <x-idempotency-key>",
    "private-secret-key: <api-key>",
    "public-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.y.uno/v2/payments/{payment_id}/transactions/{transaction_id}/cancel"

	payload := strings.NewReader("{\n  \"merchant_reference\": \"<string>\",\n  \"description\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
	req.Header.Add("public-api-key", "<api-key>")
	req.Header.Add("private-secret-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.y.uno/v2/payments/{payment_id}/transactions/{transaction_id}/cancel")
  .header("X-Idempotency-Key", "<x-idempotency-key>")
  .header("public-api-key", "<api-key>")
  .header("private-secret-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchant_reference\": \"<string>\",\n  \"description\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.y.uno/v2/payments/{payment_id}/transactions/{transaction_id}/cancel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["public-api-key"] = '<api-key>'
request["private-secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchant_reference\": \"<string>\",\n  \"description\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "7c1b6e2a-5f3d-4a8e-9b21-3e4f5a6b7c8d",
  "account_id": "493e9374-510a-4201-9e09-de669d75f256",
  "description": "Order paid with two cards",
  "country": "BR",
  "status": "CANCELED",
  "sub_status": "CANCELED",
  "merchant_order_id": "order-10045",
  "created_at": "2026-10-27T14:02:11.120Z",
  "updated_at": "2026-10-27T14:02:12.300Z",
  "split_payment_methods": true,
  "payment_methods_count": 2,
  "sdk_action_required": false,
  "amount": {
    "currency": "BRL",
    "value": 300
  },
  "checkout": {
    "session": null
  },
  "payment_method": {
    "capture": false,
    "account_updater": false,
    "payment_methods": [
      {
        "sequence": 1,
        "type": "CARD",
        "amount": {
          "currency": "BRL",
          "value": 200
        },
        "transactions": [
          {
            "id": "d2a4f6b8-1c3e-4a5b-8d7f-9e0a1b2c3d4e",
            "type": "AUTHORIZE",
            "status": "SUCCEEDED",
            "category": "CARD",
            "amount": 200,
            "provider_id": "YUNO_TEST_PAYMENT_GATEWAY",
            "response_code": "SUCCEEDED",
            "response_message": "Transaction successful",
            "reason": null,
            "description": null,
            "merchant_reference": null,
            "three_d_secure_action_required": false,
            "created_at": "2026-10-27T14:02:11.402Z",
            "updated_at": "2026-10-27T14:02:12.118Z"
          },
          {
            "id": "c7f9e1a3-6b8d-4f0a-9c2e-4d5e6f7a8b9c",
            "type": "CANCEL",
            "status": "SUCCEEDED",
            "category": "CARD",
            "amount": 200,
            "provider_id": "YUNO_TEST_PAYMENT_GATEWAY",
            "response_code": "SUCCEEDED",
            "response_message": "Transaction successful",
            "reason": null,
            "description": null,
            "merchant_reference": null,
            "three_d_secure_action_required": false,
            "created_at": "2026-10-27T14:02:11.402Z",
            "updated_at": "2026-10-27T14:02:12.118Z"
          }
        ]
      },
      {
        "sequence": 2,
        "type": "CARD",
        "amount": {
          "currency": "BRL",
          "value": 100
        },
        "transactions": [
          {
            "id": "e3b5a7c9-2d4f-4b6c-9e8a-0f1b2c3d4e5f",
            "type": "AUTHORIZE",
            "status": "SUCCEEDED",
            "category": "CARD",
            "amount": 100,
            "provider_id": "YUNO_TEST_PAYMENT_GATEWAY",
            "response_code": "SUCCEEDED",
            "response_message": "Transaction successful",
            "reason": null,
            "description": null,
            "merchant_reference": null,
            "three_d_secure_action_required": false,
            "created_at": "2026-10-27T14:02:11.402Z",
            "updated_at": "2026-10-27T14:02:12.118Z"
          }
        ]
      }
    ]
  },
  "customer_payer": {
    "id": "cfae0941-7234-427a-a739-ef4fce966c79",
    "first_name": "Ana",
    "last_name": "Souza",
    "email": "ana.souza@example.com"
  },
  "workflow": "DIRECT",
  "callback_url": "https://merchant.example.com/checkout/return",
  "metadata": []
}

{
  "code": "INVALID_PARAMETERS",
  "messages": [
    "The header 'x-idempotency-key' is required."
  ]
}

{
  "code": "INVALID_CREDENTIALS",
  "messages": [
    "Invalid credentials"
  ]
}

Getting Started

Reference

Customers

Network Tokens

Customer Sessions (Enrollment)

Checkout Sessions

Payment Methods (Checkout)

Checkout Builder

Payment Methods (Direct Workflow)

PCI Proxy

Payments

Pre-Debit Notifications

3DS2 Setup

Unreferenced Refunds

Dry-run

Transaction Reporting

Routing Recommendations

Payment Links

Recipients for Marketplace

Sellers (Franchise)

Subscriptions Plans

Subscriptions

Payouts

Organizations

Reports

Installments

AI Caller

Communications Campaigns

Conversion Rate

FX Rates

Banking Connectivity

Webhooks

Authorizations

Headers

Path Parameters

Body

Response