Criar cobrança PayIN

O PayIN permite que o merchant emita cobranças pela Orkestral. A plataforma seleciona o Provedor de Serviços de Pagamento (PSP) configurado no fluxo de pagamento e acompanha a transação até seu estado final.

Antes de começar

Você precisa:

ter um cadastro ativo na plataforma Orkestral;
cadastrar ao menos um PSP;
criar um fluxo para cada meio de pagamento utilizado;
obter um token OAuth/JWT;
conhecer o UUID do merchant (merchantId);
disponibilizar uma URL HTTPS pública caso deseje receber webhooks.

Ambientes

Ambiente	URL base
Homologação (QAS)	`https://api-qas.orkestralpay.com.br`

Solicite ao time Orkestral a URL de produção e as credenciais correspondentes. Não reutilize tokens ou credenciais entre ambientes.

Autenticação

Envie o token no header Authorization:

Authorization: Bearer <access_token>
Content-Type: application/json

Tokens são credenciais sensíveis. Não os exponha no frontend, em repositórios ou em logs.

Endpoint

POST /transaction/payin/{merchantId}

Exemplo:

curl --request POST \
  --url "https://api-qas.orkestralpay.com.br/transaction/payin/<merchantId>" \
  --header "Authorization: Bearer <access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
    "amount": 10000,
    "currency": "COP",
    "description": "Payment for services",
    "payment_method": "TRANSFER",
    "origin_url": "https://merchant.example.com/checkout",
    "ok_url": "https://merchant.example.com/payment/success",
    "error_url": "https://merchant.example.com/payment/error",
    "webhook_url": "https://merchant.example.com/webhooks/orkestral",
    "client": {
      "name": "John",
      "surname": "Doe",
      "document_type": "CC",
      "document_number": "123456789",
      "telephone": "+573001234567",
      "email": "john.doe@example.com",
      "billing_address": {
        "street": "Calle 10",
        "number": "20-30",
        "neighborhood": "Centro",
        "country": "COL",
        "state": "Antioquia",
        "city": "Medellín",
        "details": "Apartamento 101",
        "postal_code": "050001"
      }
    },
    "beneficiary_sender": {
      "name": "Jane Smith",
      "document": "987654321",
      "helpdesk": "+573009876543"
    },
    "product_info": {
      "id": "prod-001",
      "title": "Product Name",
      "description": "Product Description",
      "category_id": "services",
      "unit_price": 10000,
      "quantity": 1
    },
    "expiration": "2027-12-31T23:59:59"
  }'

Substitua datas, identificadores, URLs e credenciais pelos valores do seu ambiente. A data de expiração deve estar no futuro.

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`transaction_id`	UUID	Sim	Identificador único definido pelo merchant.
`amount`	inteiro	Sim	Valor positivo na menor unidade da moeda. Ex.: `100` = 1,00.
`currency`	string	Sim	Código da moeda em letras maiúsculas.
`description`	string	Não	Descrição da cobrança.
`payment_method`	string	Não	Meio de pagamento selecionado.
`origin_url`	string	Não	URL de origem do checkout.
`ok_url`	string	Não	Redirecionamento após sucesso.
`error_url`	string	Não	Redirecionamento após erro.
`webhook_url`	string	Não	Endpoint que receberá as atualizações.
`client`	objeto	Condicional	Dados do pagador exigidos por determinados PSPs.
`beneficiary_sender`	objeto	Condicional	Exigido pelo PSP WePayments.
`product_info`	objeto	Não	Dados do produto.
`expiration`	data/hora	Sim	Data futura no formato ISO 8601 local.

Os campos condicionais e as informações adicionais necessárias variam conforme o PSP e o meio de pagamento configurados.

Valores aceitos

Campo	Valores
`currency`	`BRL`, `COP`, `CRC`, `ECS`, `GTQ`, `PEN`, `MXN`, `NIO`, `PAB`, `HNL`, `CLP`, `SVC`, `USD`
`payment_method`	`CREDIT_CARD`, `DEBIT_CARD`, `WALLETS`, `CASH`, `TRANSFER`, `PIX`, `PSE`

O tipo de documento depende do país e do PSP. Exemplos: CPF, CNPJ, CC, CE, DNI, NIT, RFC e RUC. Use o tipo definido no cadastro e no fluxo do merchant.

Criar sem meio de pagamento

Omita payment_method quando o cliente escolherá o meio posteriormente:

{
  "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 10000,
  "currency": "COP",
  "description": "Payment for services",
  "webhook_url": "https://merchant.example.com/webhooks/orkestral",
  "expiration": "2027-12-31T23:59:59"
}

Nesse caso, a transação pode ser criada com o status WAITING_PAYMENT_METHOD. O meio deve ser informado no fluxo posterior antes do processamento pelo PSP.

Resposta de sucesso

A criação bem-sucedida retorna 201 Created. Campos opcionais variam conforme o PSP e o meio de pagamento:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "amount": 10000,
  "currency": "COP",
  "description": "Payment for services",
  "payment_method": "TRANSFER",
  "status": "WAITING_CUSTOMER_PAYMENT",
  "custom_code": "merchant-reference",
  "created_date": "2026-07-30T15:00:00",
  "country": "CO",
  "checkout_url": "https://checkout.example.com/transaction"
}

Guarde o campo id para conciliação. Não presuma que a cobrança foi paga apenas porque foi criada; use o status da resposta e os webhooks.

Tratamento de erros

HTTP	Situação comum	Ação recomendada
`400`	Campo inválido, moeda ou meio não aceito	Corrija o payload antes de repetir.
`401`	Token ausente, inválido ou expirado	Obtenha um token válido.
`403`	Credencial sem acesso ao recurso	Confira o merchant e as permissões.
`404`	Merchant ou configuração inexistente	Verifique o `merchantId` e o ambiente.
`409`	Identificador já utilizado	Não gere uma segunda cobrança sem conciliar a primeira.
`422`	Regra de negócio ou configuração do PSP inválida	Revise o PSP e o fluxo de pagamento.
`5xx`	Falha temporária	Consulte a transação antes de repetir e aplique backoff.

Não faça uma nova tentativa com outro transaction_id após timeout ou erro 5xx sem verificar se a primeira solicitação foi processada.

Webhooks

A Orkestral envia atualizações para o webhook_url da transação. Quando ele não for informado, pode ser utilizada a URL padrão cadastrada para o merchant.

O endpoint deve aceitar:

PATCH <webhook_url>
Content-Type: application/json
IP: <endereço do serviço notificador>

Payload:

{
  "status": {
    "paymentStatusId": 3,
    "name": "APPROVED"
  },
  "message": "Pagamento aprovado"
}

Responda rapidamente com um status HTTP 2xx. O notificador realiza novas tentativas quando a entrega falha; portanto, processe as notificações de forma idempotente.

Status PayIN

ID	Status
1	`WAITING_CUSTOMER_PAYMENT`
2	`EXPIRED`
3	`APPROVED`
4	`DENIED`
5	`ERROR`
8	`WAITING_PAYMENT_METHOD`
9	`CHARGEBACK`
10	`WAITING_REFUND`
11	`REFUNDED`
12	`REFUND_ERROR`
13	`DECLINED`
14	`CAPTURED`

O header IP não é uma assinatura criptográfica. Não utilize apenas esse valor para autenticar a origem da requisição.

Segurança e PCI DSS

Nunca envie PAN, CVV ou outros dados brutos de cartão nesse endpoint.
Utilize o fluxo de tokenização/SDK aprovado pela Orkestral para cartões.
Mantenha tokens exclusivamente no backend.
Não registre credenciais nem dados sensíveis em logs.
Restrinja o acesso aos dados pessoais e defina uma política de retenção.
Utilize TLS e mantenha os certificados HTTPS válidos.
A tokenização reduz a exposição, mas não elimina automaticamente as obrigações PCI DSS do merchant.

Consulte também Chave Secreta e URL de Notificação.

Antes de começar​

Ambientes​

Autenticação​

Endpoint​

Campos da requisição​

Valores aceitos​

Criar sem meio de pagamento​

Resposta de sucesso​

Tratamento de erros​

Webhooks​

Status PayIN​

Segurança e PCI DSS​