International Payments Deep Dive

International payments use the existing payment request types with additional instructions for a cross-border transfer. This page documents the request fields, a single instant example, and the validation rules.

For product-level guidance, see International Payments.

Supported Types

`type`	International create	Rules
`SingleInstantPayment`	Supported	`currencyRequest` is required.
`FixedDefinedSchedule`	Supported	`paymentSchedule` must contain exactly one entry.
`VariableDefinedSchedule`	Supported	`paymentSchedule` must contain exactly one entry.
`FixedPeriodicSchedule` / `VariablePeriodicSchedule`	Not supported	Spare rejects an international request.
`FixedOnDemand` / `VariableOnDemand`	Not supported	Spare rejects an international request.

Do not send type: InternationalPayment. Spare reserves that value for a separate request shape and rejects it at create.

Shared root fields, including creditorAccount, redirects, and signing, live on Payment Request Deep Dives.

Purpose Fields

The request contains 2 different purpose fields:

Field	Format	Description
Root `purpose`	Three-letter code	Select a code from the international Purpose Codes list.
`currencyRequest.purpose`	String	Describe the underlying reason for the transfer. This is the extended purpose, not a purpose code.

For example, root purpose can be CBP, while the extended purpose can be Payment for consulting services under invoice INV20918.

Currency Request

On SingleInstantPayment, set instructions.isInternationalPayment to true and include instructions.currencyRequest.

Field	Presence	Description
`purpose`	Required	Free-text extended purpose for the transfer.
`currencyOfTransfer`	Required	ISO 4217 currency the funds are transferred in.
`priority`	Optional	`Normal` or `Urgent`.
`chargeBearer`	Optional	`BorneByCreditor`, `BorneByDebtor`, or `Shared`.
`destinationCountryCode`	Optional	ISO country code of the payment destination.
`exchangeRateInformation`	Optional	Exchange-rate metadata for the transfer.
`fxQuoteId`	Optional	UUID of the FX quote to apply.

Example Request

This example creates a cross-border SingleInstantPayment. The root purpose is a purpose code. The nested currencyRequest.purpose is a free-text extended purpose.

Create requests require request signing. See Request Signing.

curl -X POST https://api.sandbox.tryspare.ae/payment-requests \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-tenant: UAE" \
  -H "Content-Type: application/json" \
  -H "x-signature: YOUR_REQUEST_SIGNATURE" \
  -d '{
    "type": "SingleInstantPayment",
    "creditorType": "MERCHANT",
    "creditorReference": "INV20918",
    "merchantReference": "sip-xb-inv-20918",
    "purpose": "CBP",
    "creditorAccount": {
      "schemeName": "IBAN",
      "identification": "GB29NWBK60161331926819",
      "name": "Acme Trading Ltd"
    },
    "successRedirectUrl": "https://merchant.example/payments/success",
    "failureRedirectUrl": "https://merchant.example/payments/failure",
    "instructions": {
      "amount": { "amount": "1250.00", "currency": "AED" },
      "isInternationalPayment": true,
      "currencyRequest": {
        "purpose": "Payment for consulting services under invoice INV20918",
        "currencyOfTransfer": "USD",
        "priority": "Normal",
        "chargeBearer": "Shared",
        "destinationCountryCode": "GB"
      }
    }
  }'

await client.paymentRequests.create({
  type: "SingleInstantPayment",
  creditorType: "MERCHANT",
  creditorReference: "INV20918",
  merchantReference: "sip-xb-inv-20918",
  purpose: "CBP",
  creditorAccount: {
    schemeName: "IBAN",
    identification: "GB29NWBK60161331926819",
    name: "Acme Trading Ltd",
  },
  successRedirectUrl: "https://merchant.example/payments/success",
  failureRedirectUrl: "https://merchant.example/payments/failure",
  instructions: {
    amount: { amount: "1250.00", currency: "AED" },
    isInternationalPayment: true,
    currencyRequest: {
      purpose: "Payment for consulting services under invoice INV20918",
      currencyOfTransfer: "USD",
      priority: "Normal",
      chargeBearer: "Shared",
      destinationCountryCode: "GB",
    },
  },
});

client.payment_requests.create(
    type="SingleInstantPayment",
    creditor_type="MERCHANT",
    creditor_reference="INV20918",
    merchant_reference="sip-xb-inv-20918",
    purpose="CBP",
    creditor_account={
        "schemeName": "IBAN",
        "identification": "GB29NWBK60161331926819",
        "name": "Acme Trading Ltd",
    },
    success_redirect_url="https://merchant.example/payments/success",
    failure_redirect_url="https://merchant.example/payments/failure",
    instructions={
        "amount": {"amount": "1250.00", "currency": "AED"},
        "isInternationalPayment": True,
        "currencyRequest": {
            "purpose": "Payment for consulting services under invoice INV20918",
            "currencyOfTransfer": "USD",
            "priority": "Normal",
            "chargeBearer": "Shared",
            "destinationCountryCode": "GB",
        },
    },
)

client.paymentRequests().create(
    CreatePaymentRequest.builder()
        .type("SingleInstantPayment")
        .creditorType("MERCHANT")
        .creditorReference("INV20918")
        .merchantReference("sip-xb-inv-20918")
        .purpose("CBP")
        .creditorAccount(
            Account.builder()
                .schemeName("IBAN")
                .identification("GB29NWBK60161331926819")
                .name("Acme Trading Ltd")
                .build())
        .successRedirectUrl("https://merchant.example/payments/success")
        .failureRedirectUrl("https://merchant.example/payments/failure")
        .instructions(
            PaymentInstructions.builder()
                .amount(Amount.builder().amount("1250.00").currency("AED").build())
                .isInternationalPayment(true)
                .currencyRequest(
                    CurrencyRequest.builder()
                        .purpose("Payment for consulting services under invoice INV20918")
                        .currencyOfTransfer("USD")
                        .priority("Normal")
                        .chargeBearer("Shared")
                        .destinationCountryCode("GB")
                        .build())
                .build())
        .build());

await client.PaymentRequests.CreateAsync(new CreatePaymentRequest
{
    Type = "SingleInstantPayment",
    CreditorType = "MERCHANT",
    CreditorReference = "INV20918",
    MerchantReference = "sip-xb-inv-20918",
    Purpose = "CBP",
    CreditorAccount = new Account
    {
        SchemeName = "IBAN",
        Identification = "GB29NWBK60161331926819",
        Name = "Acme Trading Ltd",
    },
    SuccessRedirectUrl = "https://merchant.example/payments/success",
    FailureRedirectUrl = "https://merchant.example/payments/failure",
    Instructions = new PaymentInstructions
    {
        Amount = new Amount { AmountValue = "1250.00", Currency = "AED" },
        IsInternationalPayment = true,
        CurrencyRequest = new CurrencyRequest
        {
            Purpose = "Payment for consulting services under invoice INV20918",
            CurrencyOfTransfer = "USD",
            Priority = "Normal",
            ChargeBearer = "Shared",
            DestinationCountryCode = "GB",
        },
    },
});

client.PaymentRequests.Create(ctx, &spareapi.CreatePaymentRequest{
    Type:              "SingleInstantPayment",
    CreditorType:      "MERCHANT",
    CreditorReference: spareapi.String("INV20918"),
    MerchantReference: "sip-xb-inv-20918",
    Purpose:           "CBP",
    CreditorAccount: &spareapi.Account{
        SchemeName:     "IBAN",
        Identification: "GB29NWBK60161331926819",
        Name:           spareapi.String("Acme Trading Ltd"),
    },
    SuccessRedirectUrl: spareapi.String("https://merchant.example/payments/success"),
    FailureRedirectUrl: spareapi.String("https://merchant.example/payments/failure"),
    Instructions: &spareapi.PaymentInstructions{
        Amount:                 &spareapi.Amount{Amount: "1250.00", Currency: "AED"},
        IsInternationalPayment: spareapi.Bool(true),
        CurrencyRequest: &spareapi.CurrencyRequest{
            Purpose:                "Payment for consulting services under invoice INV20918",
            CurrencyOfTransfer:     "USD",
            Priority:               spareapi.String("Normal"),
            ChargeBearer:           spareapi.String("Shared"),
            DestinationCountryCode: spareapi.String("GB"),
        },
    },
})

After create, collect consent through the same flow as a domestic payment. See Make Your First Payment and Payment flow.

Defined Schedule Rules

For FixedDefinedSchedule and VariableDefinedSchedule, set isInternationalPayment to true and send exactly one paymentSchedule entry.

The payment still uses that type's amount field (amount or maxAmount) and a future paymentExecutionDate. See Fixed Defined Schedule and Variable Defined Schedule.

What Fails

Spare rejects the create when:

type is InternationalPayment
isInternationalPayment is true on a periodic or on-demand type
SingleInstantPayment omits currencyRequest
currencyRequest omits the extended purpose string or currencyOfTransfer
a defined-schedule request contains more than one paymentSchedule entry
root purpose is not a valid international purpose code

See Error codes for response shapes.

Continue learning

International Payments

Choose the right cross-border payment flow.

Single Instant Payment

Single instant payment instructions.

Purpose Codes

International codes for the root purpose field.