Criar programação

curl -X POST 'https://api.goatpay.com.br/v1/transfer-scheduled/create' \
  -H 'X-API-Key: gp_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Repasse mensal",
    "triggerType": "RECURRING",
    "payload": {
      "method": "pix_padrao",
      "amount": 500,
      "description": "Repasse fornecedor",
      "pixKey": "12345678909",
      "pixKeyType": "CPF"
    },
    "recurrenceRule": {
      "interval": "monthly",
      "time": "09:00",
      "dayOfMonth": 5
    },
    "maxRuns": 12
  }'

{
  "success": true,
  "message": "Programação de transferência criada",
  "data": {
    "id": "clx_sched_01",
    "label": "Repasse mensal",
    "amount": 500,
    "method": "PIX Padrão",
    "destination": "123.456.789-09",
    "triggerType": "recurring",
    "scheduleLabel": "Todo dia 5 às 09:00",
    "nextRunAt": "2026-07-05T12:00:00.000Z",
    "lastRunAt": null,
    "runCount": 0,
    "status": "active",
    "coverFee": true
  },
  "requestId": "req_abc123"
}

{
  "success": false,
  "message": "A data do agendamento deve ser no futuro",
  "requestId": "req_err001"
}

{
  "success": false,
  "message": "Limite de 20 programações ativas atingido",
  "requestId": "req_err002"
}

POST

transfer-scheduled

create

curl -X POST 'https://api.goatpay.com.br/v1/transfer-scheduled/create' \
  -H 'X-API-Key: gp_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Repasse mensal",
    "triggerType": "RECURRING",
    "payload": {
      "method": "pix_padrao",
      "amount": 500,
      "description": "Repasse fornecedor",
      "pixKey": "12345678909",
      "pixKeyType": "CPF"
    },
    "recurrenceRule": {
      "interval": "monthly",
      "time": "09:00",
      "dayOfMonth": 5
    },
    "maxRuns": 12
  }'

{
  "success": true,
  "message": "Programação de transferência criada",
  "data": {
    "id": "clx_sched_01",
    "label": "Repasse mensal",
    "amount": 500,
    "method": "PIX Padrão",
    "destination": "123.456.789-09",
    "triggerType": "recurring",
    "scheduleLabel": "Todo dia 5 às 09:00",
    "nextRunAt": "2026-07-05T12:00:00.000Z",
    "lastRunAt": null,
    "runCount": 0,
    "status": "active",
    "coverFee": true
  },
  "requestId": "req_abc123"
}

{
  "success": false,
  "message": "A data do agendamento deve ser no futuro",
  "requestId": "req_err001"
}

{
  "success": false,
  "message": "Limite de 20 programações ativas atingido",
  "requestId": "req_err002"
}

Veja também o guia de transferências programadas.

curl -X POST 'https://api.goatpay.com.br/v1/transfer-scheduled/create' \
  -H 'X-API-Key: gp_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Repasse mensal",
    "triggerType": "RECURRING",
    "payload": {
      "method": "pix_padrao",
      "amount": 500,
      "description": "Repasse fornecedor",
      "pixKey": "12345678909",
      "pixKeyType": "CPF"
    },
    "recurrenceRule": {
      "interval": "monthly",
      "time": "09:00",
      "dayOfMonth": 5
    },
    "maxRuns": 12
  }'

{
  "success": true,
  "message": "Programação de transferência criada",
  "data": {
    "id": "clx_sched_01",
    "label": "Repasse mensal",
    "amount": 500,
    "method": "PIX Padrão",
    "destination": "123.456.789-09",
    "triggerType": "recurring",
    "scheduleLabel": "Todo dia 5 às 09:00",
    "nextRunAt": "2026-07-05T12:00:00.000Z",
    "lastRunAt": null,
    "runCount": 0,
    "status": "active",
    "coverFee": true
  },
  "requestId": "req_abc123"
}

{
  "success": false,
  "message": "A data do agendamento deve ser no futuro",
  "requestId": "req_err001"
}

{
  "success": false,
  "message": "Limite de 20 programações ativas atingido",
  "requestId": "req_err002"
}

Corpo da requisição

string

required

ONCE (agendar data), RECURRING (repetir) ou BALANCE_THRESHOLD (por saldo).

object

required

Dados da transferência a executar (ver campos abaixo).

string

required

pix_padrao, interna ou cripto.

number

required

Valor em reais (mín. R$ 0,01). Na regra por saldo, é o valor enviado (limitado ao saldo disponível).

string

Descrição da transferência.

boolean

Padrão true em PIX — amount é o valor recebido pelo destinatário.

string

Chave PIX (quando method é pix_padrao).

string

CPF, CNPJ, EMAIL, TELEFONE ou CHAVE_ALEATORIA.

string

CPF/CNPJ do titular (opcional/legado).

string

E-mail da conta destino GoatPay (quando method = interna).

string

Endereço on-chain (quando method = cripto).

string

Código da moeda/rede (cripto), ex. usdttrc20.

string

Memo/tag (cripto), quando exigido pela rede.

string

ID da subconta merchant (saque PIX da subconta).

string

ISO 8601 — obrigatório para ONCE; deve ser no futuro.

object

Obrigatório para RECURRING.

string

daily, weekly, monthly ou custom_days.

string

Horário local, ex. 09:00 (padrão 09:00).

string

Fuso IANA (padrão America/Sao_Paulo).

integer

0=domingo … 6=sábado (recorrência semanal).

integer

1–31 (recorrência mensal).

integer

Intervalo em dias (quando interval = custom_days).

number

Saldo mínimo em reais — obrigatório para BALANCE_THRESHOLD.

integer

Limite de execuções (recorrência). Omita para ilimitado (máx. 9999).

string

Nome exibido no painel (máx. 120 caracteres).

boolean

Padrão true — aplica-se à execução PIX quando não definido em payload.coverFee.

string

ID de contato salvo no dashboard (opcional).

Campos principais em `data`

Campo	Descrição
`id`	ID da programação
`label`	Rótulo ou descrição gerada
`amount`	Valor configurado no `payload`
`method`	Rótulo legível (ex. PIX Padrão, Interna)
`destination`	Chave, e-mail ou endereço mascarado
`triggerType`	`once`, `recurring` ou `balance_threshold`
`scheduleLabel`	Texto legível da regra (ex. Todo dia 5 às 09:00)
`nextRunAt`	Próxima execução (ISO) ou `—` em regra por saldo
`lastRunAt`	Última execução (ISO), se houver
`runCount`	Quantidade de execuções já realizadas
`status`	`active`, `paused`, `completed` ou `failed`
`coverFee`	Se a taxa é absorvida pelo remetente

Exemplos de `triggerType`

Agendar uma vez

{
  "triggerType": "ONCE",
  "scheduledAt": "2026-06-15T17:00:00.000Z",
  "payload": {
    "method": "interna",
    "amount": 100,
    "description": "Pagamento parceiro",
    "recipientEmail": "parceiro@empresa.com"
  }
}

Por saldo

{
  "triggerType": "BALANCE_THRESHOLD",
  "balanceThreshold": 5000,
  "payload": {
    "method": "pix_padrao",
    "amount": 1000,
    "description": "Sweep automático",
    "pixKey": "contato@email.com",
    "pixKeyType": "EMAIL"
  }
}

Limite de 20 programações ativas por conta. Transferências imediatas continuam em POST /transfer-pix/create.

Authorizations

X-API-Key

string

header

required

Chave gp_live_... criada em Integrações → Chaves de API no dashboard.

Body

application/json

triggerType

enum<string>

required

ONCE — data/hora única (scheduledAt). RECURRING — repetição (recurrenceRule). BALANCE_THRESHOLD — envia quando saldo ≥ balanceThreshold.

Available options:

ONCE,

RECURRING,

BALANCE_THRESHOLD

payload

object

required

Show child attributes

label

string

Maximum string length: 120

coverFee

boolean

default:true

scheduledAt

string<date-time>

Obrigatório para ONCE; deve ser no futuro.

recurrenceRule

object

Show child attributes

balanceThreshold

number

Saldo mínimo em reais (BALANCE_THRESHOLD).

Required range: x >= 0

maxRuns

integer

Limite de execuções (RECURRING).

Required range: 1 <= x <= 9999

contactId

string

Contato salvo no dashboard (opcional).

Response

Programação de transferência criada, consultada ou atualizada.

success

boolean

required

message

string

required

data

object

required

Show child attributes

requestId

string

Introdução

Webhooks

WebSocket

PIX

Conta

Loja

Subcontas

OAuth 2.0

Criar programação

Corpo da requisição

Campos principais em `data`

Exemplos de `triggerType`

Authorizations

Body

Response

​Corpo da requisição

​Campos principais em data

​Exemplos de triggerType

Authorizations

Body

Response

Corpo da requisição

Campos principais em `data`

Exemplos de `triggerType`