Create a payment link
curl --request POST \
--url https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/payment-links \
--header 'Content-Type: application/json' \
--data '
{
"name": "Plano anual",
"products": [
{
"product": "8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f",
"quantity": 1
}
],
"type": "ONE_TIME",
"paymentMethod": [
"PIX"
],
"firstPaymentDate": {
"pix": "SAME_DAY",
"bankSlip": "FIVE_DAYS",
"pixAutomatic": "TEN_DAYS"
},
"description": "Acesso completo por 12 meses.",
"expirationDate": "2026-12-31",
"secondaryPaymentMethod": [
"PIX"
],
"numberOfInstallments": 12
}
'import requests
url = "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/payment-links"
payload = {
"name": "Plano anual",
"products": [
{
"product": "8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f",
"quantity": 1
}
],
"type": "ONE_TIME",
"paymentMethod": ["PIX"],
"firstPaymentDate": {
"pix": "SAME_DAY",
"bankSlip": "FIVE_DAYS",
"pixAutomatic": "TEN_DAYS"
},
"description": "Acesso completo por 12 meses.",
"expirationDate": "2026-12-31",
"secondaryPaymentMethod": ["PIX"],
"numberOfInstallments": 12
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Plano anual',
products: [{product: '8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f', quantity: 1}],
type: 'ONE_TIME',
paymentMethod: ['PIX'],
firstPaymentDate: {pix: 'SAME_DAY', bankSlip: 'FIVE_DAYS', pixAutomatic: 'TEN_DAYS'},
description: 'Acesso completo por 12 meses.',
expirationDate: '2026-12-31',
secondaryPaymentMethod: ['PIX'],
numberOfInstallments: 12
})
};
fetch('https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/payment-links', 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.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/payment-links",
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([
'name' => 'Plano anual',
'products' => [
[
'product' => '8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f',
'quantity' => 1
]
],
'type' => 'ONE_TIME',
'paymentMethod' => [
'PIX'
],
'firstPaymentDate' => [
'pix' => 'SAME_DAY',
'bankSlip' => 'FIVE_DAYS',
'pixAutomatic' => 'TEN_DAYS'
],
'description' => 'Acesso completo por 12 meses.',
'expirationDate' => '2026-12-31',
'secondaryPaymentMethod' => [
'PIX'
],
'numberOfInstallments' => 12
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$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.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/payment-links"
payload := strings.NewReader("{\n \"name\": \"Plano anual\",\n \"products\": [\n {\n \"product\": \"8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f\",\n \"quantity\": 1\n }\n ],\n \"type\": \"ONE_TIME\",\n \"paymentMethod\": [\n \"PIX\"\n ],\n \"firstPaymentDate\": {\n \"pix\": \"SAME_DAY\",\n \"bankSlip\": \"FIVE_DAYS\",\n \"pixAutomatic\": \"TEN_DAYS\"\n },\n \"description\": \"Acesso completo por 12 meses.\",\n \"expirationDate\": \"2026-12-31\",\n \"secondaryPaymentMethod\": [\n \"PIX\"\n ],\n \"numberOfInstallments\": 12\n}")
req, _ := http.NewRequest("POST", url, payload)
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.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/payment-links")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Plano anual\",\n \"products\": [\n {\n \"product\": \"8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f\",\n \"quantity\": 1\n }\n ],\n \"type\": \"ONE_TIME\",\n \"paymentMethod\": [\n \"PIX\"\n ],\n \"firstPaymentDate\": {\n \"pix\": \"SAME_DAY\",\n \"bankSlip\": \"FIVE_DAYS\",\n \"pixAutomatic\": \"TEN_DAYS\"\n },\n \"description\": \"Acesso completo por 12 meses.\",\n \"expirationDate\": \"2026-12-31\",\n \"secondaryPaymentMethod\": [\n \"PIX\"\n ],\n \"numberOfInstallments\": 12\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/payment-links")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Plano anual\",\n \"products\": [\n {\n \"product\": \"8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f\",\n \"quantity\": 1\n }\n ],\n \"type\": \"ONE_TIME\",\n \"paymentMethod\": [\n \"PIX\"\n ],\n \"firstPaymentDate\": {\n \"pix\": \"SAME_DAY\",\n \"bankSlip\": \"FIVE_DAYS\",\n \"pixAutomatic\": \"TEN_DAYS\"\n },\n \"description\": \"Acesso completo por 12 meses.\",\n \"expirationDate\": \"2026-12-31\",\n \"secondaryPaymentMethod\": [\n \"PIX\"\n ],\n \"numberOfInstallments\": 12\n}"
response = http.request(request)
puts response.read_body{
"id": "5c1e8d2a-7b4f-4e3a-9d6c-2a1b0f9e8d7c",
"name": "Plano anual",
"status": "ACTIVE",
"products": [
{
"product": "8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f",
"quantity": 1
}
],
"expirationDate": "2026-12-31T00:00:00.000Z",
"type": "ONE_TIME",
"paymentMethod": [
"PIX"
],
"secondaryPaymentMethod": [
"PIX"
],
"description": "Acesso completo por 12 meses.",
"firstPaymentDate": {
"pix": "SAME_DAY",
"bankSlip": "FIVE_DAYS",
"pixAutomatic": "TEN_DAYS"
},
"numberOfInstallments": null,
"createdAt": "2026-10-26T14:30:00.000Z",
"updatedAt": "2026-10-26T14:30:00.000Z"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "PAYMENT_LINK_INVALID_PRODUCT_STATUS",
"origin": "BILLING",
"message": "Payment link products are not active"
}Create a payment link
Creates a payment link: a checkout page where payers buy the products you choose.
POST
/
realms
/
{realmId}
/
organizations
/
{organizationId}
/
payment-links
Create a payment link
curl --request POST \
--url https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/payment-links \
--header 'Content-Type: application/json' \
--data '
{
"name": "Plano anual",
"products": [
{
"product": "8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f",
"quantity": 1
}
],
"type": "ONE_TIME",
"paymentMethod": [
"PIX"
],
"firstPaymentDate": {
"pix": "SAME_DAY",
"bankSlip": "FIVE_DAYS",
"pixAutomatic": "TEN_DAYS"
},
"description": "Acesso completo por 12 meses.",
"expirationDate": "2026-12-31",
"secondaryPaymentMethod": [
"PIX"
],
"numberOfInstallments": 12
}
'import requests
url = "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/payment-links"
payload = {
"name": "Plano anual",
"products": [
{
"product": "8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f",
"quantity": 1
}
],
"type": "ONE_TIME",
"paymentMethod": ["PIX"],
"firstPaymentDate": {
"pix": "SAME_DAY",
"bankSlip": "FIVE_DAYS",
"pixAutomatic": "TEN_DAYS"
},
"description": "Acesso completo por 12 meses.",
"expirationDate": "2026-12-31",
"secondaryPaymentMethod": ["PIX"],
"numberOfInstallments": 12
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Plano anual',
products: [{product: '8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f', quantity: 1}],
type: 'ONE_TIME',
paymentMethod: ['PIX'],
firstPaymentDate: {pix: 'SAME_DAY', bankSlip: 'FIVE_DAYS', pixAutomatic: 'TEN_DAYS'},
description: 'Acesso completo por 12 meses.',
expirationDate: '2026-12-31',
secondaryPaymentMethod: ['PIX'],
numberOfInstallments: 12
})
};
fetch('https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/payment-links', 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.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/payment-links",
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([
'name' => 'Plano anual',
'products' => [
[
'product' => '8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f',
'quantity' => 1
]
],
'type' => 'ONE_TIME',
'paymentMethod' => [
'PIX'
],
'firstPaymentDate' => [
'pix' => 'SAME_DAY',
'bankSlip' => 'FIVE_DAYS',
'pixAutomatic' => 'TEN_DAYS'
],
'description' => 'Acesso completo por 12 meses.',
'expirationDate' => '2026-12-31',
'secondaryPaymentMethod' => [
'PIX'
],
'numberOfInstallments' => 12
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$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.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/payment-links"
payload := strings.NewReader("{\n \"name\": \"Plano anual\",\n \"products\": [\n {\n \"product\": \"8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f\",\n \"quantity\": 1\n }\n ],\n \"type\": \"ONE_TIME\",\n \"paymentMethod\": [\n \"PIX\"\n ],\n \"firstPaymentDate\": {\n \"pix\": \"SAME_DAY\",\n \"bankSlip\": \"FIVE_DAYS\",\n \"pixAutomatic\": \"TEN_DAYS\"\n },\n \"description\": \"Acesso completo por 12 meses.\",\n \"expirationDate\": \"2026-12-31\",\n \"secondaryPaymentMethod\": [\n \"PIX\"\n ],\n \"numberOfInstallments\": 12\n}")
req, _ := http.NewRequest("POST", url, payload)
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.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/payment-links")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Plano anual\",\n \"products\": [\n {\n \"product\": \"8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f\",\n \"quantity\": 1\n }\n ],\n \"type\": \"ONE_TIME\",\n \"paymentMethod\": [\n \"PIX\"\n ],\n \"firstPaymentDate\": {\n \"pix\": \"SAME_DAY\",\n \"bankSlip\": \"FIVE_DAYS\",\n \"pixAutomatic\": \"TEN_DAYS\"\n },\n \"description\": \"Acesso completo por 12 meses.\",\n \"expirationDate\": \"2026-12-31\",\n \"secondaryPaymentMethod\": [\n \"PIX\"\n ],\n \"numberOfInstallments\": 12\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/payment-links")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Plano anual\",\n \"products\": [\n {\n \"product\": \"8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f\",\n \"quantity\": 1\n }\n ],\n \"type\": \"ONE_TIME\",\n \"paymentMethod\": [\n \"PIX\"\n ],\n \"firstPaymentDate\": {\n \"pix\": \"SAME_DAY\",\n \"bankSlip\": \"FIVE_DAYS\",\n \"pixAutomatic\": \"TEN_DAYS\"\n },\n \"description\": \"Acesso completo por 12 meses.\",\n \"expirationDate\": \"2026-12-31\",\n \"secondaryPaymentMethod\": [\n \"PIX\"\n ],\n \"numberOfInstallments\": 12\n}"
response = http.request(request)
puts response.read_body{
"id": "5c1e8d2a-7b4f-4e3a-9d6c-2a1b0f9e8d7c",
"name": "Plano anual",
"status": "ACTIVE",
"products": [
{
"product": "8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f",
"quantity": 1
}
],
"expirationDate": "2026-12-31T00:00:00.000Z",
"type": "ONE_TIME",
"paymentMethod": [
"PIX"
],
"secondaryPaymentMethod": [
"PIX"
],
"description": "Acesso completo por 12 meses.",
"firstPaymentDate": {
"pix": "SAME_DAY",
"bankSlip": "FIVE_DAYS",
"pixAutomatic": "TEN_DAYS"
},
"numberOfInstallments": null,
"createdAt": "2026-10-26T14:30:00.000Z",
"updatedAt": "2026-10-26T14:30:00.000Z"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "PAYMENT_LINK_INVALID_PRODUCT_STATUS",
"origin": "BILLING",
"message": "Payment link products are not active"
}The link is created
ACTIVE — status is not accepted in the body. So it must be sellable right away: every product must be an active product of your organization’s catalog with a price above zero, and expirationDate, when sent, must be today or later.
Each checkout of the link creates a contract and a deal for the payer, charging the products’ prices at that moment. Any member of the organization, or an admin of the realm, can create one; createdBy and updatedBy are set to the ID of the authenticated caller.Path Parameters
ID of your realm.
Format: UUID
ID of your organization: the one that sells through the link.
Format: UUID
Body
application/json
Name of the link. The checkout page shows it to the payer, and it becomes the description of the deal each checkout creates.
Required string length:
2 - 56Example:
"Plano anual"
What the link sells. At least one. The amount charged is the products' current prices times their quantities, read at each checkout.
Minimum array length:
1Show child attributes
Show child attributes
ONE_TIME: each checkout charges once. RECURRENT: each checkout charges numberOfInstallments times, monthly.
Available options:
RECURRENT, ONE_TIME Example:
"ONE_TIME"
The ways the payer can choose from at checkout: BANK_SLIP (boleto), PIX (a PIX charge), PIX_AUTOMATIC (PIX Automático: the payer authorizes the recurring payments once) or PIX_INITIATION (recurring scheduled PIX, authorized the same way). A RECURRENT link with PIX_AUTOMATIC needs numberOfInstallments above 1 and firstPaymentDate.pixAutomatic.
Example: ["PIX","BANK_SLIP"]
Minimum array length:
1Available options:
BANK_SLIP, PIX_INITIATION, PIX, PIX_AUTOMATIC When the first payment of a checkout is due, counted from the checkout day: SAME_DAY, ONE_DAY, FIVE_DAYS, TEN_DAYS, THIRTY_DAYS, SIXTY_DAYS, or EXPIRATION_DATE (the link's expirationDate; the checkout day when it has none). At least one key. One value applies to every checkout, whatever method the payer picks: pixAutomatic when set, otherwise bankSlip, otherwise pix.
Show child attributes
Show child attributes
What the link sells, shown on the checkout page.
Maximum string length:
250Example:
"Acesso completo por 12 meses."
Last day the link can be paid: an ISO 8601 date (YYYY-MM-DD, read as midnight UTC) or a date-time with an offset. Today or later. The link can be paid through that day: the daily expiry run, at 03:01 UTC (00:01 in Brasília) of the following day, turns it EXPIRED, which is final. Omit it for a link that never expires.
Example:
"2026-12-31"
Other ways each invoice can also be paid, whatever the payer chose — typically PIX and/or BANK_SLIP alongside PIX_AUTOMATIC or PIX_INITIATION.
Example: ["PIX"]
Available options:
BANK_SLIP, PIX_INITIATION, PIX, PIX_AUTOMATIC How many monthly payments a checkout of a RECURRENT link creates. Above 1 for a RECURRENT link with PIX_AUTOMATIC. Omitted or null: 1.
Required range:
x >= 1Example:
12
Response
Successful response
A payment link.
ID of the payment link. The checkout page of the link is addressed by it.
Example:
"5c1e8d2a-7b4f-4e3a-9d6c-2a1b0f9e8d7c"
Name of the link.
Example:
"Plano anual"
ACTIVE: payers can check out. DEACTIVATED: switched off; it can be activated again. EXPIRED: its expirationDate passed; final.
Available options:
ACTIVE, DEACTIVATED, EXPIRED Example:
"ACTIVE"
What the link sells.
Show child attributes
Show child attributes
Last day the link can be paid (midnight UTC of that day), or null when it never expires.
Example:
"2026-12-31T00:00:00.000Z"
ONE_TIME: each checkout charges once. RECURRENT: monthly, numberOfInstallments times.
Available options:
RECURRENT, ONE_TIME Example:
"ONE_TIME"
The ways the payer can choose from at checkout.
Example: ["PIX","BANK_SLIP"]
Available options:
BANK_SLIP, PIX_INITIATION, PIX, PIX_AUTOMATIC Other ways each invoice can also be paid. Empty when there are none.
Example: ["PIX"]
Available options:
BANK_SLIP, PIX_INITIATION, PIX, PIX_AUTOMATIC What the link sells. Absent when it has none.
Example:
"Acesso completo por 12 meses."
When the first payment of a checkout is due, per payment method.
Show child attributes
Show child attributes
How many monthly payments a checkout of a RECURRENT link creates, or null (1).
Example:
null
When the link was created.
Example:
"2026-10-26T14:30:00.000Z"
When the link was last changed.
Example:
"2026-10-26T14:30:00.000Z"