Initiate PIX Payment

POST

orders

{orderId}

initiate

pix

Initiate PIX Payment

curl --request POST \
  --url https://api.vertracloud.app/v1/orders/{orderId}/initiate/pix \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vertracloud.app/v1/orders/{orderId}/initiate/pix', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.vertracloud.app/v1/orders/{orderId}/initiate/pix"

headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

package main

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

func main() {

	url := "https://api.vertracloud.app/v1/orders/{orderId}/initiate/pix"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

{
  "response": {
    "transaction_amount": 24.9,
    "external_reference": "order-abc123",
    "txid": "9c2b1e3a-...-000",
    "expires_at": "2026-10-13T15:30:00.000Z",
    "qrcode": {
      "copy": "00020126...6304ABCD",
      "base64": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  }
}

string

required

The order ID.

Each QR code is valid for up to 30 minutes (expires_at), never past the order’s own expiry. Calling this again while the QR code is still valid returns the same one. After it expires, calling this again while the order is still open returns a new QR code for the same order.

Response

object

Show Toggle object

number

The charge amount, in BRL.

string | null

The order ID, echoed back as the payment’s external reference.

string

The PIX transaction ID.

string | null

When this QR code stops being payable, in ISO 8601 (up to 30 minutes after it was generated, never after the order expires).

object

Show Toggle object

string | null

The copy-and-paste PIX code.

string | null

The QR code image, base64-encoded.

{
  "response": {
    "transaction_amount": 24.9,
    "external_reference": "order-abc123",
    "txid": "9c2b1e3a-...-000",
    "expires_at": "2026-10-13T15:30:00.000Z",
    "qrcode": {
      "copy": "00020126...6304ABCD",
      "base64": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  }
}

Error Responses

string

The error code indicating the reason for failure. Possible values:

AUTH_TOKEN_MISSING, API_KEY_INVALID, SESSION_REVOKED: The Authorization header is missing, the API key is invalid, or the dashboard session was revoked (401).
API_KEY_IP_DENIED, API_KEY_SCOPE_DENIED: The API key is used from an IP outside its allowlist, or it lacks the scope the route requires (403).
USER_NOT_FOUND: The authenticated user was not found.
ORDER_NOT_FOUND: The specified order does not exist.
FORBIDDEN: The order does not belong to the authenticated user.
ORDER_NOT_PAYABLE: The order is already paid, cancelled, or has expired (400), or a card payment of the order is still being confirmed (409).
COUPON_PAYMENT_METHOD: The order’s coupon doesn’t allow PIX.
PAYMENT_METHOD_UNAVAILABLE: Online payment is temporarily unavailable.
INVALID_PARAMS: The orderId is malformed.
RATE_LIMIT_EXCEEDED: Another payment of the account is being started. Try again shortly.
INTERNAL_SERVER_ERROR: An unexpected server error occurred.

{
  "code": "ORDER_NOT_PAYABLE"
}

Last modified on October 26, 2026

Initiate PIX Payment

curl --request POST \
  --url https://api.vertracloud.app/v1/orders/{orderId}/initiate/pix \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vertracloud.app/v1/orders/{orderId}/initiate/pix', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.vertracloud.app/v1/orders/{orderId}/initiate/pix"

headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

package main

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

func main() {

	url := "https://api.vertracloud.app/v1/orders/{orderId}/initiate/pix"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

{
  "response": {
    "transaction_amount": 24.9,
    "external_reference": "order-abc123",
    "txid": "9c2b1e3a-...-000",
    "expires_at": "2026-10-13T15:30:00.000Z",
    "qrcode": {
      "copy": "00020126...6304ABCD",
      "base64": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  }
}

Overview

Endpoints

Response

Error Responses

​Response

​Error Responses

Response

Error Responses