> ## Documentation Index
> Fetch the complete documentation index at: https://docs.afriex.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Settlement Advice
> Returns a short-lived presigned download URL for the settlement & remittance advice PDF auto-generated for a USD withdrawal from your collection wallet (a withdrawal created with `settlement: "request"`). The advice is issued with status `PENDING` when the withdrawal is created and regenerated with status `COMPLETED` (same reference, incremented version) once the withdrawal succeeds. Scoped to your business: you can only fetch advices for your own transactions. This document is a settlement and remittance advice, not a tax invoice.
Returns a short-lived (5 minute) presigned download URL for the settlement & remittance advice PDF that Afriex auto-generates for a USD withdrawal from your **Collection wallet**, i.e. a `WITHDRAW` created with `meta.settlement: "request"`.
Advices are only generated for USD withdrawals with `meta.settlement: "request"`. Requesting an advice for any other transaction returns `404`.
## Lifecycle
The advice is issued twice for the same transaction:
When the withdrawal is created, an advice is generated with `status: "PENDING"` and `version: 1`.
Once the withdrawal succeeds, the advice is regenerated as `status: "COMPLETED"` with an incremented `version`. The `reference` stays the same across regenerations.
## The document
This is a **settlement and remittance advice**, not a tax invoice. Use it to reconcile the settlement leg of a collection-wallet USD withdrawal.
## Scope and access
Advices are scoped to your business: you can only fetch advices for transactions you created. The download `url` is a presigned S3 URL valid for 5 minutes. Fetch a fresh URL by calling this endpoint again when the current one expires.
## OpenAPI
````yaml GET /api/v1/transaction/{transactionId}/advice
openapi: 3.1.0
info:
title: Afriex Business API
version: 1.0.8
description: >-
Welcome to the Afriex Business API. This API allows you to manage customers,
process payments, handle payouts, and receive real-time notifications via
webhooks.
For detailed guidance on authentication, pagination, error handling, and
webhooks, please refer to the [dedicated guides](https://docs.afriex.com) in
the top bar. The guide provides a step-by-step instructions to help you
integrate seamlessly.
termsOfService: https://www.afriex.com/terms-and-condition
contact:
name: Afriex API Support
email: support@afriex.com
url: https://docs.afriex.com
license:
name: Proprietary
url: https://www.afriex.com/terms-and-condition
servers:
- url: https://sandbox.api.afriex.com
description: Staging Base URL
- url: https://api.afriex.com
description: Production Base URL
security:
- ApiKey: []
tags:
- name: Customers
description: Create and manage your customers.
- name: Payment Methods
description: Register and resolve customer payout and collection methods.
- name: Transactions
description: Create and track deposits, withdrawals, and swaps.
- name: Balance
description: View and top up your business wallet balances.
- name: Rates
description: Fetch real-time exchange rates.
- name: Checkout Sessions
description: Create hosted checkout sessions.
- name: Webhooks
description: Webhook event payloads and sandbox webhook testing.
- name: Media
description: Generate presigned URLs for secure file uploads.
paths:
/api/v1/transaction/{transactionId}/advice:
parameters:
- $ref: '#/components/parameters/x-api-signature'
- $ref: '#/components/parameters/x-api-version'
get:
tags:
- Transactions
summary: Get settlement & remittance advice
description: >-
Returns a short-lived presigned download URL for the settlement &
remittance advice PDF auto-generated for a USD withdrawal from your
collection wallet (a withdrawal created with `settlement: "request"`).
The advice is issued with status `PENDING` when the withdrawal is
created and regenerated with status `COMPLETED` (same reference,
incremented version) once the withdrawal succeeds. Scoped to your
business: you can only fetch advices for your own transactions. This
document is a settlement and remittance advice, not a tax invoice.
operationId: getTransactionAdvice
parameters:
- name: transactionId
in: path
description: The unique identifier of the transaction
required: true
schema:
type: string
responses:
'200':
description: Settlement advice download URL retrieved successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
url:
type: string
description: >-
Short-lived (5 minute) presigned S3 URL for the advice
PDF.
reference:
type: string
description: >-
Stable advice reference number. Generated once per
transaction and reused across regenerations.
status:
type: string
enum:
- PENDING
- COMPLETED
description: >-
PENDING until the withdrawal succeeds, COMPLETED
afterwards.
version:
type: integer
description: >-
Regeneration counter. Starts at 1 at creation and
increments when the advice is regenerated on
completion.
generatedAt:
type: string
format: date-time
examples:
success:
summary: Advice retrieved
value:
data:
url: >-
https://example-bucket.s3.amazonaws.com/.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Signature=...
reference: ADV-EXAMPLE-0001
status: PENDING
version: 1
generatedAt: '2026-01-01T00:00:00.000Z'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingApiKey:
summary: Missing API key
value:
code: AUTHENTICATION_ERROR
error: Authorization header is missing
details: {}
invalidApiKey:
summary: Invalid API key
value:
code: AUTHENTICATION_ERROR
error: Invalid authorization header
details: {}
'404':
description: >-
Transaction not found, or no settlement advice exists for this
transaction (only USD withdrawals from the collection wallet
qualify).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
notFound:
summary: Transaction or advice not found
value:
code: BUSINESS_TRANSACTION_NOT_FOUND
error: Business transaction not found
details:
errorMessage: No settlement advice exists for this transaction
friendlyMessage: ''
'500':
description: Server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
serverError:
summary: Unexpected server error
value:
code: INTERNAL_SERVER_ERROR
error: It's not you, it's us, please reach out to support
details: {}
x-codeSamples:
- lang: TypeScript
label: Afriex SDK
source: >
const advice = await
afriex.transactions.getAdvice("transaction-id");
components:
parameters:
x-api-signature:
name: x-api-signature
in: header
required: false
description: >-
Signature of the request payload, used for request authentication where
payload signing is enabled for your business.
schema:
type: string
x-api-version:
name: x-api-version
in: header
required: false
description: >-
API version in ISO 8601 format (e.g. 2025-12-28). Defaults to latest
stable.
schema:
type: string
schemas:
ErrorResponse:
type: object
properties:
code:
type: string
description: Machine-readable error code.
error:
type: string
description: Human-readable error message.
details:
$ref: '#/components/schemas/ErrorDetails'
ErrorDetails:
type: object
properties:
errorMessage:
type: string
description: Detailed/technical error message.
friendlyMessage:
type: string
description: User-facing error message safe to display.
data:
type: object
description: >-
Optional caller-safe context for the error. On a customer-create
uniqueness conflict (EMAIL_ALREADY_EXISTS /
PHONE_NUMBER_ALREADY_EXISTS) this carries the existing customer's
id, so you can adopt it without a follow-up lookup.
properties:
customerId:
type: string
description: Id of the existing customer (on a create conflict).
securitySchemes:
ApiKey:
type: apiKey
in: header
name: x-api-key
description: >-
Static business API key issued from the dashboard. A business can
provision **multiple API keys**, each scoped to a configurable set of
**permissions** (e.g. read transactions, create deposits, etc).
Permissions are chosen per key at creation time in the dashboard and may
be revoked by deleting the key. Requests made with a key that does not
include the permission required by the target endpoint will be rejected
with a `403 Forbidden` response; an unrecognised, malformed or revoked
key returns `401 Unauthorized`. Manage your keys and their permissions
under **Developer → API keys** in the dashboard.
````