CrossBorderPaymentsService
in package
Implements SEP-0031 - Cross-Border Payments API (for sending anchors).
SECURITY: Payment matching relies exclusively on the stellar_memo field. The source account may differ from the SEP-10 authenticated account. Anchors must NEVER use source account for payment matching.
SECURITY: When handling PII/KYC data, ensure HTTPS is enforced, sensitive data is encrypted at rest, and GDPR/privacy regulations are followed.
Tags
Table of Contents
Methods
- __construct() : mixed
- Constructor.
- fromDomain() : CrossBorderPaymentsService
- Creates an instance of this class by loading the anchor direct payment server SEP-31 url from the given domain stellar toml file (DIRECT_PAYMENT_SERVER).
- getTransaction() : SEP31TransactionResponse
- The transaction endpoint enables Sending Clients to fetch information on a specific transaction with the Receiving Anchor.
- info() : SEP31InfoResponse
- Allows an anchor to communicate basic info about what currencies their DIRECT_PAYMENT_SERVER supports receiving from partner anchors.
- patchTransaction() : void
- (Deprecated) This endpoint should only be used when the Receiving Anchor needs more info via the pending_transaction_info_update status from the Sending Anchor.
- postTransactions() : SEP31PostTransactionsResponse
- This request initiates a payment. The Sending and Receiving Client must be registered via SEP-12 if required by the Receiving Anchor.
- putTransactionCallback() : void
- This endpoint can be used by the Sending Anchor to register a callback URL that the Receiving Anchor will make application/json POST requests to containing the transaction object defined in the response to GET /transaction/:id whenever the transaction's status value has changed. Note that a callback does not need to be made for the initial status of the transaction, which in most cases is pending_sender.
Methods
__construct()
Constructor.
public
__construct(string $serviceAddress[, Client|null $httpClient = null ]) : mixed
Parameters
- $serviceAddress : string
-
for the server (DIRECT_PAYMENT_SERVER in stellar.toml).
- $httpClient : Client|null = null
-
to be used for requests. If not provided, this service will use its own http client.
fromDomain()
Creates an instance of this class by loading the anchor direct payment server SEP-31 url from the given domain stellar toml file (DIRECT_PAYMENT_SERVER).
public
static fromDomain(string $domain[, Client|null $httpClient = null ]) : CrossBorderPaymentsService
Parameters
- $domain : string
-
to load the service address from.
- $httpClient : Client|null = null
-
to be used for requests. If not provided, this service will use its own http client.
Tags
Return values
CrossBorderPaymentsService —the initialized QuoteService
getTransaction()
The transaction endpoint enables Sending Clients to fetch information on a specific transaction with the Receiving Anchor.
public
getTransaction(string $id, string $jwt) : SEP31TransactionResponse
Parameters
- $id : string
-
the id of the transaction.
- $jwt : string
-
JWT token obtained from SEP-10 Web Authentication using the Sending Anchor's account. The authenticated account must be pre-authorized by the Receiving Anchor via bilateral agreement.
Tags
Return values
SEP31TransactionResponse —the transaction data if the response status code is 200 OK.
info()
Allows an anchor to communicate basic info about what currencies their DIRECT_PAYMENT_SERVER supports receiving from partner anchors.
public
info(string $jwt[, string|null $lang = null ]) : SEP31InfoResponse
Parameters
- $jwt : string
-
JWT token obtained from SEP-10 Web Authentication using the Sending Anchor's account. The authenticated account must be pre-authorized by the Receiving Anchor via bilateral agreement.
- $lang : string|null = null
-
Defaults to en. Language code specified using ISO 639-1.
Tags
Return values
SEP31InfoResponse —object containing the response data on response with status 200 OK.
patchTransaction()
(Deprecated) This endpoint should only be used when the Receiving Anchor needs more info via the pending_transaction_info_update status from the Sending Anchor.
public
patchTransaction(string $id, array<string|int, mixed> $fields, string $jwt) : void
since SEP-31 v2.5.0, use SEP-12 PUT /customer instead
The required_info_updates transaction field should contain the fields required for the update. If the Sending Anchor tries to update at a time when no info is requested, the Receiving Anchor should fail with an error response.
DEPRECATED: This approach is deprecated in favor of using per-customer fields provided via SEP-9 fields in SEP-12 PUT /customer requests. Use SEP-12 for all new implementations.
Parameters
- $id : string
-
the id of the transaction.
- $fields : array<string|int, mixed>
-
A key-pair object containing the values requested to be updated by the receiving anchor in the same format as fields in the POST /transactions request.
- $jwt : string
-
JWT token obtained from SEP-10 Web Authentication.
Tags
postTransactions()
This request initiates a payment. The Sending and Receiving Client must be registered via SEP-12 if required by the Receiving Anchor.
public
postTransactions(SEP31PostTransactionsRequest $request, string $jwt) : SEP31PostTransactionsResponse
Parameters
- $request : SEP31PostTransactionsRequest
-
the request data.
- $jwt : string
-
JWT token obtained from SEP-10 Web Authentication using the Sending Anchor's account. The authenticated account must be pre-authorized by the Receiving Anchor via bilateral agreement.
Tags
Return values
SEP31PostTransactionsResponse —the response data if status code is 201 Created or 200 OK.
putTransactionCallback()
This endpoint can be used by the Sending Anchor to register a callback URL that the Receiving Anchor will make application/json POST requests to containing the transaction object defined in the response to GET /transaction/:id whenever the transaction's status value has changed. Note that a callback does not need to be made for the initial status of the transaction, which in most cases is pending_sender.
public
putTransactionCallback(string $id, string $callbackUrl, string $jwt) : void
SECURITY: Receiving Anchors must include a signature in the Signature or X-Stellar-Signature HTTP header for all callback requests. Sending Anchors must verify this signature using the Receiving Anchor's SIGNING_KEY from their stellar.toml file.
The signature covers: timestamp + "." + hostname + "." + request_body
Sending Anchors must:
- Verify signature against Receiving Anchor's SIGNING_KEY from stellar.toml
- Check timestamp freshness (reject requests older than 1-2 minutes)
- Validate request body matches transaction schema
- Use HTTPS exclusively for callback URLs
Parameters
- $id : string
-
id of the transaction.
- $callbackUrl : string
-
the callback url (must use HTTPS)
- $jwt : string
-
JWT token obtained from SEP-10 Web Authentication using the Sending Anchor's account. The authenticated account must be pre-authorized by the Receiving Anchor via bilateral agreement.