> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goatpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Obter token
> Troca authorization code ou refresh token por access token.
Corpo **`application/x-www-form-urlencoded`** (RFC 6749). Resposta no formato OAuth2 puro — **sem** envelope `{ success, message, data }`.
```bash Authorization code theme={null}
curl -X POST 'https://api.goatpay.com.br/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=authorization_code' \
-d 'client_id=gp_oauth_live_...' \
-d 'client_secret=SEU_SECRET' \
-d 'code=CODE_DO_CALLBACK' \
-d 'redirect_uri=https://sua-app.com/oauth/callback' \
-d 'code_verifier=SEU_VERIFIER'
```
```bash Refresh token theme={null}
curl -X POST 'https://api.goatpay.com.br/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=refresh_token' \
-d 'client_id=gp_oauth_live_...' \
-d 'client_secret=SEU_SECRET' \
-d 'refresh_token=gp_ort_...'
```
```bash client_secret_basic theme={null}
curl -X POST 'https://api.goatpay.com.br/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-u 'gp_oauth_live_...:SEU_SECRET' \
-d 'grant_type=authorization_code' \
-d 'code=CODE_DO_CALLBACK' \
-d 'redirect_uri=https://sua-app.com/oauth/callback' \
-d 'code_verifier=SEU_VERIFIER'
```
```json Success theme={null}
{
"access_token": "gp_oat_live_...",
"token_type": "Bearer",
"expires_in": 900,
"refresh_token": "gp_ort_...",
"scope": "account:read payments:read"
}
```
```json Erro theme={null}
{
"error": "invalid_grant",
"error_description": "The authorization code is invalid or expired"
}
```
### Corpo (form-urlencoded)
`authorization_code` ou `refresh_token`.
Client ID da aplicação.
Obrigatório para clients confidential.
Código do callback — com `grant_type=authorization_code`.
Mesma URI usada no authorize.
PKCE verifier — com `grant_type=authorization_code`.
Com `grant_type=refresh_token`. O refresh anterior é invalidado (rotação).
Access tokens expiram em **15 minutos** (`expires_in: 900`). Renove com refresh antes de expirar.
## OpenAPI
````yaml POST /oauth/token
openapi: 3.1.0
info:
title: GoatPay API
description: >
API pública merchant da GoatPay. Autenticação via header `X-API-Key:
gp_live_...`.
Respostas de sucesso usam o envelope `{ success, message, data, requestId
}`.
Campos internos (`accountId`, `metadata`, histórico de entregas de webhook,
etc.) não são expostos.
`providerTransactionId` aparece como `referenceId`; `providerInfractionId`
como `infractionId`.
Rate limit global: 100 requisições por minuto por API key (HTTP 429). Sem
chave, limite por IP.
version: 1.0.0
servers:
- url: https://api.goatpay.com.br/v1
description: Produção
security:
- apiKeyAuth: []
tags:
- name: pix
description: >-
Cobranças PIX (receber), reembolsos de depósito recebido e transferências
PIX (enviar). Alias legado em payouts/* para envios.
- name: transfer-internal
description: Transferências entre contas GoatPay
- name: transfer-scheduled
description: Transferências programadas (agendar, repetir ou por saldo)
- name: crypto
description: Depósitos e transferências em criptomoeda
- name: billings
description: >-
Cobranças avulsas (pagamento único) — boleto, cartão ou PIX na Conta
Padrão (PF ou PJ)
- name: subscriptions
description: >-
Assinaturas recorrentes com ciclo fixo — boleto, cartão ou PIX na Conta
Padrão (PF ou PJ)
- name: account
description: Saldo e extrato
- name: subaccount
description: Subcontas merchant (carteiras lógicas sob a conta principal)
- name: meds
description: Disputas MED
- name: webhooks
description: Endpoints de webhook de saída
- name: oauth
description: OAuth 2.0 — autorização de terceiros (fora do prefixo /v1)
- name: oauth-apps
description: Gestão de aplicações OAuth (prefixo /v1, API key)
- name: payouts
description: Alias de transfer-pix para saques PIX
- name: customers
description: Clientes da loja (CRM)
- name: products
description: Produtos e entregas digitais
- name: coupons
description: Cupons de desconto para links
- name: payment-links
description: Links de pagamento e checkout hospedado
paths:
/oauth/token:
post:
tags:
- oauth
summary: Obter ou renovar token
description: |
Troca `authorization_code` por tokens ou renova com `refresh_token`.
Corpo `application/x-www-form-urlencoded` (RFC 6749).
operationId: oauthToken
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/OAuthTokenRequest'
examples:
authorization_code:
summary: Trocar code por tokens
value:
grant_type: authorization_code
client_id: gp_oauth_live_...
client_secret: SEU_SECRET
code: CODE_DO_CALLBACK
redirect_uri: https://sua-app.com/oauth/callback
code_verifier: SEU_VERIFIER
refresh_token:
summary: Renovar access token
value:
grant_type: refresh_token
client_id: gp_oauth_live_...
client_secret: SEU_SECRET
refresh_token: gp_ort_...
responses:
'200':
$ref: '#/components/responses/OAuthTokenSuccess'
'400':
description: Erro OAuth (invalid_grant, unsupported_grant_type, etc.)
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
security: []
servers:
- url: https://api.goatpay.com.br
description: Raiz da API (sem /v1)
components:
schemas:
OAuthTokenRequest:
type: object
required:
- grant_type
- client_id
properties:
grant_type:
type: string
enum:
- authorization_code
- refresh_token
client_id:
type: string
client_secret:
type: string
code:
type: string
redirect_uri:
type: string
format: uri
code_verifier:
type: string
refresh_token:
type: string
OAuthError:
type: object
properties:
error:
type: string
example: invalid_grant
error_description:
type: string
OAuthTokenResponse:
type: object
required:
- access_token
- token_type
- expires_in
properties:
access_token:
type: string
example: gp_oat_live_...
token_type:
type: string
example: Bearer
expires_in:
type: integer
example: 900
refresh_token:
type: string
example: gp_ort_...
scope:
type: string
example: account:read payments:read
responses:
OAuthTokenSuccess:
description: Tokens emitidos.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthTokenResponse'
examples:
default:
value:
access_token: gp_oat_live_...
token_type: Bearer
expires_in: 900
refresh_token: gp_ort_...
scope: account:read payments:read
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Chave `gp_live_...` criada em Integrações → Chaves de API no dashboard.
````