Referência da API

Criar transação (BOB)

Cria uma transação de entrada em BOB (bolivianos) por QR. Mesmo endpoint do PIX — POST /transactions/v2/purchase — mudando currency para "BOB". O payload do QR NÃO vem nesta resposta — chega alguns segundos depois, por GET /transactions/:id. Conceitos e fluxo completo em Bolívia (BOB).

POST/transactions/v2/purchase

Mostre o QR E um botão de copiar

qr Quem abre o seu checkout no celular não consegue escanear, com o mesmo celular, um QR exibido na tela dele. Renderize a imagem e, logo abaixo, o mesmo payload como texto com botão copiar — o campo qr serve para os dois. Ignorar isso trava o comprador numa tela que parece funcionar.

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

namestringobrigatório

Nome completo do pagador (máximo 255 caracteres).

Exemplo: Ana Flores

emailstringobrigatório

E-mail válido do pagador. Obrigatório na Bolívia — a rede recusa a cobrança sem ele.

Exemplo: ana@ejemplo.com

phonestringobrigatório

Telefone do pagador com DDI. Obrigatório na Bolívia.

Exemplo: 59171234567

amountnumberobrigatório

Valor em centavos de boliviano. Bs 100,00 = 10000. A rede aceita de BOB 10 a BOB 10.000 por transação — a faixa mais estreita entre as moedas que operamos.

Exemplo: 10000

descriptionstringobrigatório

Descrição curta da transação que aparece no comprovante do pagador.

Exemplo: Suscripción Pro

responsibleDocumentstringobrigatório

Documento do pagador boliviano — CI, NIT ou PAS. Obrigatório.

Exemplo: 1234567

responsibleExternalIdstringobrigatório

ID interno do responsável no seu sistema (ex: ID do vendedor, ID da conta).

Exemplo: user-1234

currency'BOB'obrigatório

Código da moeda. Para Bolívia use "BOB". O amount continua em CENTAVOS (10000 = Bs 100,00). Omitir currency cai no padrão BRL (PIX).

Exemplo: BOB

paymentMethod'QR'opcional

Opcional para currency: BOB — default QR. (No BRL, PIX é obrigatório.)

Exemplo: QR

cpfstringopcional

Não usado em BOB — é um documento brasileiro. O documento do pagador boliviano vai em responsibleDocument.

externalIdstringopcional

Sua referência para essa transação. Retornada em GET /transactions/:id?searchBy=externalId e em todo webhook vinculado a essa transação.

Exemplo: pedido-5678

postbackUrlstringopcional

URL de webhook para eventos dessa transação. Se omitido, usa a URL global do dashboard.

Exemplo: https://seu-dominio.com/webhook

Body da requisição

Content-Type: application/json

JSON

{
  "name": "Ana Flores",
  "email": "ana@ejemplo.com",
  "phone": "59171234567",
  "amount": 10000,
  "currency": "BOB",
  "description": "Suscripción Pro",
  "responsibleDocument": "1234567",
  "responsibleExternalId": "user-1234",
  "externalId": "pedido-5678",
  "postbackUrl": "https://seu-dominio.com/webhook"
}

Respostas

201

Cobrança criada. qr vem vazio — é o esperado: o payload é gerado pela rede boliviana e chega em alguns segundos. Busque em GET /transactions/:id até vir preenchido. status fica PENDING até o pagamento cair (webhook cashin.paid).

JSON

{
  "id": "17864385245624641191295936",
  "currency": "BOB",
  "method": "QR",
  "installments": null,
  "externalId": "pedido-5678",
  "status": "PENDING",
  "amount": 10000,
  "postbackUrl": "https://seu-dominio.com/webhook",
  "referrerUrl": null,
  "qr": null,
  "expiresAt": null,
  "createdAt": "2026-09-02T08:55:24.748Z",
  "costFee": 300
}

400

Erro de validação — inclui valor fora da faixa aceita pela rede (BOB 10 a BOB 10.000) e falta de phone, email ou documento do pagador.

JSON

{
  "statusCode": 400,
  "message": "The 'amount' is outside the range accepted for BOB.",
  "error": "Bad Request"
}

401

API key inválida ou ausente.

JSON

{ "statusCode": 401, "message": "Unauthorized" }

403

API key sem a permissão createTransaction.

JSON

{ "statusCode": 403, "message": "Forbidden" }

Exemplos

bash

curl -X POST "https://api.ihubplay.com/transactions/v2/purchase" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana Flores",
    "email": "ana@ejemplo.com",
    "phone": "59171234567",
    "amount": 10000,
    "currency": "BOB",
    "description": "Suscripción Pro",
    "responsibleDocument": "1234567",
    "responsibleExternalId": "user-1234",
    "postbackUrl": "https://seu-dominio.com/webhook"
  }'