Skip to main content
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"
}
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"
}

​
Corpo da requisição

​
triggerType
string
required
ONCE (agendar data), RECURRING (repetir) ou BALANCE_THRESHOLD (por saldo).
​
payload
object
required
Dados da transferência a executar (ver campos abaixo).
​
payload.method
string
required
pix_padrao, pix_livre, interna ou cripto.
​
payload.amount
number
required
Valor em reais (mín. R$ 0,01). Na regra por saldo, é o valor enviado (limitado ao saldo disponível).
​
payload.description
string
Descrição da transferência.
​
payload.coverFee
boolean
Padrão true em PIX — amount é o valor recebido pelo destinatário.
​
payload.pixKey
string
Chave PIX (quando method é pix_padrao ou pix_livre).
​
payload.pixKeyType
string
CPF, CNPJ, EMAIL, TELEFONE ou CHAVE_ALEATORIA.
​
payload.pixKeyOwnerDocument
string
CPF/CNPJ do titular (opcional/legado).
​
payload.recipientEmail
string
E-mail da conta destino GoatPay (quando method = interna).
​
payload.address
string
Endereço on-chain (quando method = cripto).
​
payload.payCurrency
string
Código da moeda/rede (cripto), ex. usdttrc20.
​
payload.extraId
string
Memo/tag (cripto), quando exigido pela rede.
​
payload.subaccountId
string
ID da subconta merchant (saque PIX da subconta).
​
scheduledAt
string
ISO 8601 — obrigatório para ONCE; deve ser no futuro.
​
recurrenceRule
object
Obrigatório para RECURRING.
​
recurrenceRule.interval
string
daily, weekly, monthly ou custom_days.
​
recurrenceRule.time
string
Horário local, ex. 09:00 (padrão 09:00).
​
recurrenceRule.timezone
string
Fuso IANA (padrão America/Sao_Paulo).
​
recurrenceRule.dayOfWeek
integer
0=domingo … 6=sábado (recorrência semanal).
​
recurrenceRule.dayOfMonth
integer
1–31 (recorrência mensal).
​
recurrenceRule.customDays
integer
Intervalo em dias (quando interval = custom_days).
​
balanceThreshold
number
Saldo mínimo em reais — obrigatório para BALANCE_THRESHOLD.
​
maxRuns
integer
Limite de execuções (recorrência). Omita para ilimitado (máx. 9999).
​
label
string
Nome exibido no painel (máx. 120 caracteres).
​
coverFee
boolean
Padrão true — aplica-se à execução PIX quando não definido em payload.coverFee.
​
contactId
string
ID de contato salvo no dashboard (opcional).

​
Campos principais em data

CampoDescrição
idID da programação
labelRótulo ou descrição gerada
amountValor configurado no payload
methodRótulo legível (ex. PIX Padrão, Interna)
destinationChave, e-mail ou endereço mascarado
triggerTypeonce, recurring ou balance_threshold
scheduleLabelTexto legível da regra (ex. Todo dia 5 às 09:00)
nextRunAtPróxima execução (ISO) ou — em regra por saldo
lastRunAtÚltima execução (ISO), se houver
runCountQuantidade de execuções já realizadas
statusactive, paused, completed ou failed
coverFeeSe 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_livre",
    "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
​
label
string
Maximum string length: 120
​
coverFee
boolean
default:true
​
scheduledAt
string<date-time>

Obrigatório para ONCE; deve ser no futuro.

​
recurrenceRule
object
​
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
​
requestId
string