PT EN

Pagamentos

URL base: $CONNECTOR_API

Registar um conector de pagamento

Registos

POST /payments/registrations

Exchange a payment enrollment token for a connector session token

The token binds the session to one tenant. A request may assert tenant_id, and is refused when it differs from the token's tenant. operational_methods lists the supported methods the connector can actually complete; a skeleton provider declares none.

Corpo application/json

tokenstring · obrigatório

One-time payment connector enrollment token

namestring · opcional
supported_methodsarray of string · opcional
operational_methodsarray of string · opcional
currencystring · opcional
hostnamestring · opcional
agent_versionstring · opcional
tenant_idstring · opcional

Devolve

201 Connector registered

Erros 400

curl -X POST "$CONNECTOR_API/payments/registrations" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "token": "token",
  "name": "Ana Matsinhe",
  "supported_methods": [
    "supported method"
  ],
  "operational_methods": [
    "operational method"
  ],
  "currency": "MZN",
  "hostname": "hostname",
  "agent_version": "agent version",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6"
}'
Resposta 201

Connector registered

Pedir o próximo pagamento a processar

Registos

POST /payments/jobs/request

Long-poll for the next payment job and refresh the operational_methods declaration

Leases the next pending payment job (a collection or a refund) for the calling connector, filtered by the methods and currency in the body or, when omitted, the ones the connector registered. Set wait_timeout_seconds (capped at 50) to long-poll: the call waits for a new job and returns 204 No Content when none arrives in time. A leased job is held for 60 seconds and must be kept alive with the heartbeat call; the body can also declare which registered methods are currently operational, which controls what consumers are offered at checkout.

Devolve

200 A leased job for the connector's tenant

Erros 401

curl -X POST "$CONNECTOR_API/payments/jobs/request" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

A leased job for the connector's tenant

Renovar a reserva de um pagamento

Registos

POST /payments/jobs/{id}/heartbeat

Extends the lease on a job the calling connector holds by another 60 seconds and marks the connector busy. Call it while a payment is still in progress so the job is not handed to another connector. Returns 404 when the job does not exist, is not leased by this connector or has already been completed.

Parâmetros

idstring · caminho · obrigatório

Identifier of the leased payment job (prefixed pjb_) whose lease should be extended.

Devolve

200 Lease renewed

Erros 404

curl -X POST "$CONNECTOR_API/payments/jobs/{id}/heartbeat" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Lease renewed

Comunicar o resultado de um pagamento

Registos

POST /payments/jobs/{id}/complete

Reports the outcome of a job the calling connector holds; status must be succeeded or failed. For a collection, success confirms the payment against its payment session (recording the payment, receipt and invoice allocation) and failure marks a still-pending session as failed; a refund's outcome is only stored on the job. Settlement runs before the job closes and every step is idempotent, so retrying after an error is safe. Returns 404 for an unknown job, 401 when another connector holds it, and 409 when the job is no longer leased.

Parâmetros

idstring · caminho · obrigatório

Identifier of the leased payment job (prefixed pjb_) returned by the job request call.

Devolve

200 Outcome recorded

Erros 409

curl -X POST "$CONNECTOR_API/payments/jobs/{id}/complete" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Outcome recorded

Comunicar um pagamento recebido

Registos

POST /payments/events

Records a settled payment that a payment connector observed on its own, such as a customer paying at an agent or from a phone menu, without a prior payment job. The connector authenticates with its connector token (Authorization Bearer or Token, or X-Connector-Token); provider_transaction_id and a positive amount_minor are required, and the payment is matched to the tenant's account by account_number, with settled_at defaulting to now. Confirmation is idempotent on the provider transaction and event_id, so a repeated event does not post the payment twice. Returns 401 for an unknown token and 403 when the tenant is suspended or closed.

Devolve

200 Event ingested

Erros 400

curl -X POST "$CONNECTOR_API/payments/events" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Event ingested

Esperar pelo próximo trabalho de pagamento (caminho antigo)

Registos

POST /payments/request

Long-poll for the next payment job (older path)

Older path for the payment job request; it runs the same handler as $CONNECTOR_API/payments/jobs/request and behaves identically, so new connectors should call that path instead. Leases the next pending payment job for the calling connector, filtered by the methods and currency in the body or, when omitted, the ones the connector registered, and can refresh the connector's operational methods. Set wait_timeout_seconds (capped at 50) to long-poll; 204 means no job arrived in time. The connector session token is accepted as Authorization Bearer or Token, or in the X-Connector-Token header.

Corpo application/json

supported_methodsarray of string · opcional

Methods to lease jobs for; defaults to the methods the connector registered.

operational_methodsarray of string · opcional

When present, replaces the connector's declaration of which registered methods are operational now (methods it did not register are dropped). Absent leaves the declaration unchanged; an empty list declares none operational.

currencystring · opcional

Currency to lease jobs for; defaults to the connector's registered currency.

wait_timeout_secondsinteger · opcional

Seconds to wait for a job before answering 204; values above 50 are capped and negative values mean no wait.

Devolve

200 A leased job for the connector's tenant

Erros 401 · 403

curl -X POST "$CONNECTOR_API/payments/request" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "supported_methods": [
    "supported method"
  ],
  "operational_methods": [
    "operational method"
  ],
  "currency": "MZN",
  "wait_timeout_seconds": 0
}'
Resposta 200

A leased job for the connector's tenant