Criar link de pagamento

Crie um link de pagamento na My Gateway: atributos do payload, formas de pagamento, itens e cupons, e exemplo de resposta.

Nesta página

POST/payments/v1/checkout

Cria um link que pode ser compartilhado com o pagador.

Cabeçalhos

Authorizationstringobrigatório
Valor de authenticationToken retornado na autenticação, sem o prefixo Bearer.
x-api-keystringobrigatório
Chave do API Gateway do ambiente.

Content-Typestringobrigatório
Sempre application/json.

Corpo da requisição

valueintegerobrigatório
Valor total do link em centavos. Maior que zero.
main_titlestringobrigatório
Título principal exibido no checkout. Não pode ser vazio nem igual a title ou description, ignorando maiúsculas e minúsculas.
titlestringobrigatório
Título do link ou pedido. Não pode ser vazio nem igual a main_title ou description.
descriptionstringobrigatório
Descrição do pagamento. Não pode ser vazia nem igual a main_title ou title.
validitystring (ISO 8601)obrigatório
Data de expiração. Precisa ser futura. Recomenda-se UTC com sufixo Z.
minimum_number_of_installmentsintegerobrigatório
Menor quantidade de parcelas permitida, de 1 a 21.
maximum_number_of_installmentsintegerobrigatório
Maior quantidade de parcelas permitida, de 1 a 21. Não pode ser menor que o mínimo.
number_of_allowed_salesintegerobrigatório
Quantidade máxima de pagamentos permitidos pelo link. Maior que zero.
is_show_form_addressbooleanobrigatório
Quando true, pede o endereço no formulário do checkout.
is_customer_interestbooleanobrigatório
Indica se os juros do parcelamento ficam com o pagador.
accepted_payments_typearray de integerobrigatório
Formas de pagamento aceitas. Precisa ter ao menos um código válido.
Valores aceitos: 1 2
checkout_itemsobjectopcional
Composição detalhada do valor. Quando enviado, precisa obedecer à regra de fechamento.
Atributos de checkout_items
- discountintegerobrigatório
  Desconto total em centavos. Maior ou igual a zero.
- couponsarrayopcional
  Cupons que compõem o desconto. A soma dos cupons não pode passar de discount.
  Atributos de coupons
  namestringobrigatório
  Nome ou código do cupom.
  valueintegerobrigatório
  Valor do cupom em centavos.
- itemsarrayobrigatório
  Itens que compõem o checkout.
  Atributos de items
  namestringobrigatório
  Nome ou descrição do item.
  total_valueintegerobrigatório
  Valor total da linha em centavos. A API soma este campo diretamente, então ele já deve considerar a quantidade.
  quantitynumberobrigatório
  Quantidade comercial do item. Pode ter casas decimais quando a unidade de venda permitir.
  imagestring (URL)obrigatório
  URL pública da imagem do item. Recomenda-se HTTPS.
originstring (URL)opcional
URL de origem da criação, por exemplo a página do pedido no sistema integrador. Se preenchida, precisa ser uma URL válida.
segmentstringopcional
Segmento ou contexto comercial informado pelo integrador, por exemplo ecommerce ou marketing.

Corpo da requisição

{
  "value": 15000,
  "main_title": "Pagamento do pedido 12345",
  "title": "Pedido 12345",
  "description": "Pagamento referente aos produtos do pedido 12345",
  "validity": "2027-04-03T23:59:59Z",
  "minimum_number_of_installments": 1,
  "maximum_number_of_installments": 3,
  "number_of_allowed_sales": 1,
  "is_show_form_address": true,
  "is_customer_interest": false,
  "accepted_payments_type": [
    1,
    2
  ],
  "checkout_items": {
    "discount": 1000,
    "coupons": [
      {
        "name": "PROMO10",
        "value": 1000
      }
    ],
    "items": [
      {
        "name": "Produto A",
        "total_value": 10000,
        "quantity": 1,
        "image": "https://integrador.exemplo.com/assets/produto-a.png"
      },
      {
        "name": "Produto B",
        "total_value": 6000,
        "quantity": 2,
        "image": "https://integrador.exemplo.com/assets/produto-b.png"
      }
    ]
  },
  "origin": "https://integrador.exemplo.com/pedidos/12345",
  "segment": "ecommerce"
}

No exemplo: R$ 100,00 + R$ 60,00 - R$ 10,00 = R$ 150,00, por isso a composição de checkout_items corresponde a value: 15000.

Requisição

# link.json: o corpo da requisição mostrado acima
curl --request POST \
  --url 'https://api.mygateway.com.br/payments/v1/checkout' \
  --header 'Authorization: TOKEN_DE_AUTENTICACAO' \
  --header 'x-api-key: SUA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data @link.json

// payload: o corpo da requisição mostrado acima

const response = await fetch("https://api.mygateway.com.br/payments/v1/checkout", {
  method: "POST",
  headers: {
    Authorization: token,
    "x-api-key": process.env.MYGATEWAY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

const result = await response.json();

<?php
// $payload: o corpo da requisição mostrado acima
$ch = curl_init('https://api.mygateway.com.br/payments/v1/checkout');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: ' . $token,
        'x-api-key: ' . getenv('MYGATEWAY_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);

import os
import requests

# payload: o corpo da requisição mostrado acima
response = requests.post(
    "https://api.mygateway.com.br/payments/v1/checkout",
    headers={
        "Authorization": token,
        "x-api-key": os.environ["MYGATEWAY_API_KEY"],
    },
    json=payload,
)
result = response.json()

Respostas

Link criado.

JSON

{
  "data": {
    "id": "f4d8488c-aed0-4828-8b46-723ab7249f08",
    "link": "https://checkout.mygateway.com.br/AbC123xYz789"
  }
}

Payload inválido, regra de negócio não atendida, UUID vazio ou inválido, ou registro não localizado. Veja Erros.

ValidationError

{
  "notificationErrors": {
    "error": {
      "errors": [
        {
          "propertyName": "Value",
          "propertyErrors": [
            "O valor informado não pode ser igual ou menor que zero"
          ]
        }
      ]
    }
  },
  "errorTypeDescription": "ValidationError",
  "errorType": 1
}

Token ausente, inválido, expirado ou sem autorização.

JSON

{
  "errorId": "identificador-para-suporte",
  "message": "Não autorizado",
  "encryptdetail": "detalhe-tecnico",
  "timestamp": "2026-10-29T17:40:00Z",
  "ip": "203.0.113.10"
}

Atributos da resposta

data.idUUIDobrigatório
Identificador do link. Use-o como payment-link-id nas consultas.
data.linkstring (URL)obrigatório
URL que deve ser aberta ou compartilhada com o pagador.

Formas de pagamento aceitas#

Código enviado	Nome retornado	Descrição
`1`	`PIX`	Pagamento instantâneo via PIX.
`2`	`Credit`	Cartão de crédito.

O valor 0 (None) não é aceito. A API também entende os nomes do enum sem diferenciar maiúsculas de minúsculas, mas o contrato recomendado para a criação são os códigos numéricos.

Itens, cupons e desconto#

O objeto checkout_items é opcional e detalha como o valor do link é composto. Quando ele é enviado, a soma dos itens menos o desconto precisa ser exatamente igual a value:

Regra de fechamento

soma(items[*].total_value) - checkout_items.discount = value

A soma dos valores dos cupons não pode ultrapassar discount.
total_value é o valor total da linha, já considerando a quantidade.
Todos os valores de checkout_items são em centavos.

Última atualização em 29 de outubro de 2026

Criar link de pagamento

Formas de pagamento aceitas#

Itens, cupons e desconto#

Soluções

Taxa

Empresa

Políticas

Suporte