Bloobank API Documentation

Cancel payment order

curl --request PUT \
  --url https://txengine.bloobank.com/txengine/v1/wallets/{wallet}/paymentOrders/{paymentOrder}/cancel \
  --header 'X-Access-Key: <api-key>' \
  --header 'X-Access-Request-Id: <api-key>' \
  --header 'X-Access-Signature: <api-key>' \
  --header 'X-Access-Timestamp: <api-key>'

import requests

url = "https://txengine.bloobank.com/txengine/v1/wallets/{wallet}/paymentOrders/{paymentOrder}/cancel"

headers = {
    "X-Access-Key": "<api-key>",
    "X-Access-Timestamp": "<api-key>",
    "X-Access-Request-Id": "<api-key>",
    "X-Access-Signature": "<api-key>"
}

response = requests.put(url, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {
    'X-Access-Key': '<api-key>',
    'X-Access-Timestamp': '<api-key>',
    'X-Access-Request-Id': '<api-key>',
    'X-Access-Signature': '<api-key>'
  }
};

fetch('https://txengine.bloobank.com/txengine/v1/wallets/{wallet}/paymentOrders/{paymentOrder}/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://txengine.bloobank.com/txengine/v1/wallets/{wallet}/paymentOrders/{paymentOrder}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => [
    "X-Access-Key: <api-key>",
    "X-Access-Request-Id: <api-key>",
    "X-Access-Signature: <api-key>",
    "X-Access-Timestamp: <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"
	"net/http"
	"io"
)

func main() {

	url := "https://txengine.bloobank.com/txengine/v1/wallets/{wallet}/paymentOrders/{paymentOrder}/cancel"

	req, _ := http.NewRequest("PUT", url, nil)

	req.Header.Add("X-Access-Key", "<api-key>")
	req.Header.Add("X-Access-Timestamp", "<api-key>")
	req.Header.Add("X-Access-Request-Id", "<api-key>")
	req.Header.Add("X-Access-Signature", "<api-key>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://txengine.bloobank.com/txengine/v1/wallets/{wallet}/paymentOrders/{paymentOrder}/cancel")
  .header("X-Access-Key", "<api-key>")
  .header("X-Access-Timestamp", "<api-key>")
  .header("X-Access-Request-Id", "<api-key>")
  .header("X-Access-Signature", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://txengine.bloobank.com/txengine/v1/wallets/{wallet}/paymentOrders/{paymentOrder}/cancel")

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

request = Net::HTTP::Put.new(url)
request["X-Access-Key"] = '<api-key>'
request["X-Access-Timestamp"] = '<api-key>'
request["X-Access-Request-Id"] = '<api-key>'
request["X-Access-Signature"] = '<api-key>'

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

{
  "id": "ord_3KpFvBwYzNqMxA7eHbRdJ",
  "kind": "Payment.Order",
  "wallet": "production-main",
  "ordVersion": 2,
  "direction": "IN",
  "status": "AWAITING_APPROVAL",
  "network": "br.gov.bcb.pix",
  "idempotencyKey": "invoice-2026-0184",
  "amount": 25000,
  "currency": "BRL",
  "instrument": {
    "type": "PIX_CASH_IN_EMV_STATIC",
    "endToEndId": "<string>"
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "selfName": "wallets/production-main/paymentOrders/ord_3KpFvBwYzNqMxA7eHbRdJ",
  "etag": "<string>",
  "metadata": {
    "orderId": "2026-0184"
  },
  "errorCode": "<string>",
  "errorMessage": "<string>",
  "processedAt": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": 400,
    "status": "INVALID_ARGUMENT",
    "message": "Filter expression references an unsupported field.",
    "details": [
      {
        "reason": "INVALID_ARGUMENT",
        "description": "Field `nonexistent` is not allowed for filtering on this endpoint.",
        "metadata": {}
      }
    ]
  }
}

{
  "error": {
    "code": 401,
    "status": "SIGNATURE_INVALID",
    "message": "Request signature could not be verified.",
    "details": [
      {
        "reason": "SIGNATURE_INVALID",
        "description": "The provided signature does not match the canonical request.",
        "metadata": {
          "decisionId": "acd_9RmKvTpYzH2wN8qJ5b"
        }
      }
    ]
  }
}

{
  "error": {
    "code": 403,
    "status": "RBAC_DENY",
    "message": "The credential is not permitted to perform this action.",
    "details": [
      {
        "reason": "RBAC_DENY",
        "description": "Missing required role binding on the target resource.",
        "metadata": {
          "decisionId": "acd_8PaJvNqLcK3xW5sR4d"
        }
      }
    ]
  }
}

{
  "error": {
    "code": 404,
    "status": "WALLET_NOT_FOUND",
    "message": "Wallet not found.",
    "details": [
      {
        "reason": "WALLET_NOT_FOUND",
        "description": "No wallet exists with name `production-main`.",
        "metadata": {}
      }
    ]
  }
}

{
  "error": {
    "code": 422,
    "status": "PAYMENT_ORDER_NOT_AWAITING_APPROVAL",
    "message": "Payment order is not awaiting approval.",
    "details": [
      {
        "reason": "PAYMENT_ORDER_NOT_AWAITING_APPROVAL",
        "description": "The payment order must be in AWAITING_APPROVAL for this operation.",
        "metadata": {}
      }
    ]
  }
}

{
  "error": {
    "code": 429,
    "status": "RESOURCE_EXHAUSTED",
    "message": "Rate limit exceeded for this credential.",
    "details": [
      {
        "reason": "RESOURCE_EXHAUSTED",
        "description": "You have exceeded the request quota for this endpoint.",
        "metadata": {
          "retry_after_seconds": 12
        }
      }
    ]
  }
}

{
  "error": {
    "code": 500,
    "status": "INTERNAL",
    "message": "An unexpected error occurred.",
    "details": [
      {
        "reason": "INTERNAL",
        "description": "Internal server error.",
        "metadata": {
          "id": "exc_5KaHsBxYzW3pM2dV"
        }
      }
    ]
  }
}

{
  "error": {
    "code": 503,
    "status": "PROVIDER_UNAVAILABLE",
    "message": "Upstream payment provider is unavailable.",
    "details": [
      {
        "reason": "PROVIDER_UNAVAILABLE",
        "description": "The provider returned a transient error or did not respond.",
        "metadata": {
          "id": "exc_5KaHsBxYzW3pM2dV"
        }
      }
    ]
  }
}

PUT

wallets

{wallet}

paymentOrders

{paymentOrder}

cancel

Cancel payment order

curl --request PUT \
  --url https://txengine.bloobank.com/txengine/v1/wallets/{wallet}/paymentOrders/{paymentOrder}/cancel \
  --header 'X-Access-Key: <api-key>' \
  --header 'X-Access-Request-Id: <api-key>' \
  --header 'X-Access-Signature: <api-key>' \
  --header 'X-Access-Timestamp: <api-key>'

import requests

url = "https://txengine.bloobank.com/txengine/v1/wallets/{wallet}/paymentOrders/{paymentOrder}/cancel"

headers = {
    "X-Access-Key": "<api-key>",
    "X-Access-Timestamp": "<api-key>",
    "X-Access-Request-Id": "<api-key>",
    "X-Access-Signature": "<api-key>"
}

response = requests.put(url, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {
    'X-Access-Key': '<api-key>',
    'X-Access-Timestamp': '<api-key>',
    'X-Access-Request-Id': '<api-key>',
    'X-Access-Signature': '<api-key>'
  }
};

fetch('https://txengine.bloobank.com/txengine/v1/wallets/{wallet}/paymentOrders/{paymentOrder}/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://txengine.bloobank.com/txengine/v1/wallets/{wallet}/paymentOrders/{paymentOrder}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => [
    "X-Access-Key: <api-key>",
    "X-Access-Request-Id: <api-key>",
    "X-Access-Signature: <api-key>",
    "X-Access-Timestamp: <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"
	"net/http"
	"io"
)

func main() {

	url := "https://txengine.bloobank.com/txengine/v1/wallets/{wallet}/paymentOrders/{paymentOrder}/cancel"

	req, _ := http.NewRequest("PUT", url, nil)

	req.Header.Add("X-Access-Key", "<api-key>")
	req.Header.Add("X-Access-Timestamp", "<api-key>")
	req.Header.Add("X-Access-Request-Id", "<api-key>")
	req.Header.Add("X-Access-Signature", "<api-key>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://txengine.bloobank.com/txengine/v1/wallets/{wallet}/paymentOrders/{paymentOrder}/cancel")
  .header("X-Access-Key", "<api-key>")
  .header("X-Access-Timestamp", "<api-key>")
  .header("X-Access-Request-Id", "<api-key>")
  .header("X-Access-Signature", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://txengine.bloobank.com/txengine/v1/wallets/{wallet}/paymentOrders/{paymentOrder}/cancel")

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

request = Net::HTTP::Put.new(url)
request["X-Access-Key"] = '<api-key>'
request["X-Access-Timestamp"] = '<api-key>'
request["X-Access-Request-Id"] = '<api-key>'
request["X-Access-Signature"] = '<api-key>'

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

{
  "id": "ord_3KpFvBwYzNqMxA7eHbRdJ",
  "kind": "Payment.Order",
  "wallet": "production-main",
  "ordVersion": 2,
  "direction": "IN",
  "status": "AWAITING_APPROVAL",
  "network": "br.gov.bcb.pix",
  "idempotencyKey": "invoice-2026-0184",
  "amount": 25000,
  "currency": "BRL",
  "instrument": {
    "type": "PIX_CASH_IN_EMV_STATIC",
    "endToEndId": "<string>"
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "selfName": "wallets/production-main/paymentOrders/ord_3KpFvBwYzNqMxA7eHbRdJ",
  "etag": "<string>",
  "metadata": {
    "orderId": "2026-0184"
  },
  "errorCode": "<string>",
  "errorMessage": "<string>",
  "processedAt": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": 400,
    "status": "INVALID_ARGUMENT",
    "message": "Filter expression references an unsupported field.",
    "details": [
      {
        "reason": "INVALID_ARGUMENT",
        "description": "Field `nonexistent` is not allowed for filtering on this endpoint.",
        "metadata": {}
      }
    ]
  }
}

{
  "error": {
    "code": 401,
    "status": "SIGNATURE_INVALID",
    "message": "Request signature could not be verified.",
    "details": [
      {
        "reason": "SIGNATURE_INVALID",
        "description": "The provided signature does not match the canonical request.",
        "metadata": {
          "decisionId": "acd_9RmKvTpYzH2wN8qJ5b"
        }
      }
    ]
  }
}

{
  "error": {
    "code": 403,
    "status": "RBAC_DENY",
    "message": "The credential is not permitted to perform this action.",
    "details": [
      {
        "reason": "RBAC_DENY",
        "description": "Missing required role binding on the target resource.",
        "metadata": {
          "decisionId": "acd_8PaJvNqLcK3xW5sR4d"
        }
      }
    ]
  }
}

{
  "error": {
    "code": 404,
    "status": "WALLET_NOT_FOUND",
    "message": "Wallet not found.",
    "details": [
      {
        "reason": "WALLET_NOT_FOUND",
        "description": "No wallet exists with name `production-main`.",
        "metadata": {}
      }
    ]
  }
}

{
  "error": {
    "code": 422,
    "status": "PAYMENT_ORDER_NOT_AWAITING_APPROVAL",
    "message": "Payment order is not awaiting approval.",
    "details": [
      {
        "reason": "PAYMENT_ORDER_NOT_AWAITING_APPROVAL",
        "description": "The payment order must be in AWAITING_APPROVAL for this operation.",
        "metadata": {}
      }
    ]
  }
}

{
  "error": {
    "code": 429,
    "status": "RESOURCE_EXHAUSTED",
    "message": "Rate limit exceeded for this credential.",
    "details": [
      {
        "reason": "RESOURCE_EXHAUSTED",
        "description": "You have exceeded the request quota for this endpoint.",
        "metadata": {
          "retry_after_seconds": 12
        }
      }
    ]
  }
}

{
  "error": {
    "code": 500,
    "status": "INTERNAL",
    "message": "An unexpected error occurred.",
    "details": [
      {
        "reason": "INTERNAL",
        "description": "Internal server error.",
        "metadata": {
          "id": "exc_5KaHsBxYzW3pM2dV"
        }
      }
    ]
  }
}

{
  "error": {
    "code": 503,
    "status": "PROVIDER_UNAVAILABLE",
    "message": "Upstream payment provider is unavailable.",
    "details": [
      {
        "reason": "PROVIDER_UNAVAILABLE",
        "description": "The provider returned a transient error or did not respond.",
        "metadata": {
          "id": "exc_5KaHsBxYzW3pM2dV"
        }
      }
    ]
  }
}

Cancels an outbound payment order awaiting approval. Transitions status from AWAITING_APPROVAL to CANCELED without submitting it to the provider — no money moves.

Preconditions

Condition	Failure
Order must be `direction: OUT`.	`PAYMENT_ORDER_INVALID_STATE` (HTTP 422).
Order must be in `AWAITING_APPROVAL`.	`PAYMENT_ORDER_INVALID_STATE` (HTTP 422).

Cancel is only valid before approval. Once an order moves to PENDING (after approve), it cannot be canceled — it will run to completion on the provider’s timeline. To reverse a successful payment, you need a separate refund flow, not a cancel.

Effect

status → CANCELED (terminal)
locked on the wallet is unchanged (the order never reserved funds — reservation happens at approve)
The order is never submitted to the provider

The CANCELED state is terminal. Once an order is canceled, it cannot be revived; if you need to re-attempt the operation, create a new order with a different idempotencyKey.

Authorizations

X-Access-Key

string

header

required

Opaque credential identifier provisioned during onboarding. See the Integration Guide for the request-signing protocol.

X-Access-Timestamp

string

header

required

Unix epoch timestamp in UTC milliseconds. See the Integration Guide for skew tolerance.

X-Access-Request-Id

string

header

required

Unique identifier per request (UUID v4 recommended). The (accessKey, requestId) tuple must be unique within the replay window defined by the Integration Guide.

X-Access-Signature

string

header

required

Base64-encoded ECDSA signature of the canonical request, computed with the private key paired to X-Access-Key. See the Integration Guide for canonicalization rules and reference implementations.

Path Parameters

wallet

string

required

Wallet name (RFC 1035 DNS label).

Required string length: 1 - 63

Pattern: ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$

paymentOrder

string

required

Payment order identifier.

Pattern: ^ord_[A-Za-z0-9]+$

Response

The canceled payment order.

An inbound (cash-in) or outbound (cash-out) payment request routed through a provider network on behalf of a wallet.

string

required

read-only

Pattern: ^ord_[A-Za-z0-9]+$

Example:

"ord_3KpFvBwYzNqMxA7eHbRdJ"

kind

enum<string>

required

read-only

Available options:

Payment.Order

wallet

string

required

read-only

The wallet that owns this order (DNS label name).

Example:

"production-main"

ordVersion

integer

required

read-only

Snapshot version, incremented on every content mutation.

Required range: x >= 1

direction

enum<string>

required

Direction of value flow.

Available options:

IN,

OUT

status

enum<string>

required

Lifecycle status of a payment order.

Available options:

AWAITING_APPROVAL,

PENDING,

PROCESSING,

SUCCESS,

FAILED,

CANCELED,

EXPIRED,

REFUNDED

network

enum<string>

required

Payment network identifier.

Available options:

br.gov.bcb.pix,

tron.mainnet,

solana.mainnet,

bitcoin.mainnet,

ethereum.mainnet

idempotencyKey

string

required

Client-supplied opaque key. The (wallet, idempotencyKey) tuple is globally unique; identical retries return the existing order, divergent retries return IDEMPOTENCY_KEY_IN_USE_WITH_DIFFERENT_PARAMS.

Required string length: 1 - 64

Example:

"invoice-2026-0184"

amount

integer<int64>

required

Amount in minor units of the order currency.

Required range: x >= 1

Example:

25000

currency

enum<string>

required

Currency or asset code.

Available options:

BRL,

USD,

TRX,

SOL,

BTC,

ETH,

USDT

instrument

object

required

Inbound PIX instrument backed by a long-lived, reusable static EMV QR code.

Option 1
Option 2
Option 3
Option 4
Option 5

Show child attributes

createdAt

string<date-time>

required

read-only

Server-assigned creation timestamp (UTC ISO 8601).

updatedAt

string<date-time>

required

read-only

Timestamp of the last content mutation (UTC ISO 8601).

selfName

string

required

read-only

Canonical relative resource name.

Example:

"wallets/production-main/paymentOrders/ord_3KpFvBwYzNqMxA7eHbRdJ"

etag

string

required

read-only

Hex-encoded content fingerprint of the resource. Reserved for optimistic concurrency control via the If-Match request header in a future release; currently exposed for informational and audit purposes only.

Pattern: ^[a-f0-9]{64,128}$

metadata

object

Client-supplied tags. Not included in the etag computation.

Show child attributes

Example:

{ "orderId": "2026-0184" }

errorCode

string | null

read-only

Provider-reported error code when status is FAILED.

errorMessage

string | null

read-only

Human-readable error description when status is FAILED.

processedAt

string<date-time> | null

read-only

Server processing timestamp. null until the order is submitted to (or rejected by) the underlying provider; set once the provider returns a definitive outcome.

Introduction

Conventions

Wallets

Payment Orders

Utilities

Cancel payment order

Preconditions

Effect

Authorizations

Path Parameters

Response

​Preconditions

​Effect

Authorizations

Path Parameters

Response

Preconditions

Effect