Credentials and request safety

Issue, replace and revoke

Payline must admit your organization and integration first. An admitted organization manager opens Account → Developer Settings from the partner access page. Check the organization, integration, environment and API base URL before issuing. Secrets are shown once by the application: copy the secret into your server’s secret store before selecting Done or leaving the dialog. Switching tabs can hide it. There is no later application secret-reveal operation. A replacement keeps the same stable integration identity. Move your server to the replacement, confirm the cutover, then explicitly revoke the predecessor; replacement alone does not revoke it. Revocation denies new requests using that key, but does not cancel an already authenticated operation or revoke merchant URLs. An authorized manager can still revoke credentials after integration use is disabled. If delivery is interrupted, use Check status. Do not blindly issue again. The application reconciles the attempt and revokes an identified undelivered key before allowing fresh issuance. If it remains uncertain, contact Payline without sharing secrets.

Authenticate from your server

Send Authorization: Bearer <key> on each API request. JSON writes use Content-Type: application/json. The verified credential and current local grant determine tenant, environment, integration and capabilities; request fields cannot select them. The relevant capabilities are applications:create, applications:read, applications:eligible-users:read and applications:handoff:reissue. For the shell examples, supply PAYLINE_API_KEY through your approved secret manager; do not type a real key into shell history. Disable shell tracing. Each example uses the Sandbox base below and requires curl; commands that inspect JSON also use jq.

set +x
umask 077
export PAYLINE_API_BASE='https://sandbox.paylinedata.com/api/v1'
: "${PAYLINE_API_KEY:?Load the Sandbox key through your secret manager}"

The commands save responses to restricted local files instead of printing protected answers or merchant URLs. Use a private working directory and delete local response files when no longer needed under your retention policy. Do not send them to telemetry, shared build logs or support. Do not paste API keys into browser code, URLs or chat.

Errors, limits and retries

Errors contain a safe error.code, error.message, field paths/codes, error.retryable and a supportReference. Field errors do not echo submitted values. Share only safe support references and the operation/time when asking for help.

Response	Action
`401 unauthenticated`	Check the correct environment and credential; do not retry indefinitely.
`403 capability_denied`	Confirm current admission and capability with Payline.
`404 not_found`	Check the identifier and authorized integration scope.
`409 request_conflict`	The request ID was reused with different intent. Reconcile the original operation.
`422 validation_failed`	Correct the reported fields before a new valid operation.
`429 rate_limited`	Wait for `Retry-After` before retrying.
`503 operation_unconfirmed` or a lost response	For create/reissue, retry the identical request ID and original body after backoff. Never generate a new ID just because the response was lost.

Per stable caller, the implementation allows 30 create attempts, 30 separate reissue attempts and 120 shared GET attempts per 60-second window. Replacement keys do not reset these counters. Poll with backoff; these limits are not a throughput SLA. Responses are no-store; your own clients must also avoid caching sensitive results.

Start

Application lifecycle

Issue, replace and revoke

Authenticate from your server

Errors, limits and retries

​Issue, replace and revoke

​Authenticate from your server

​Errors, limits and retries

Issue, replace and revoke

Authenticate from your server

Errors, limits and retries