Simulate SWIFT Deposit (Sandbox)

In sandbox, a SWIFT transfer to an account's SWIFT receiving account is simulated with one API call: you tell Avenia that a transfer arrived, with its amount and its sender, and the deposit then goes through the same processing as in production. Avenia creates the ticket, converts the USD to USDC, credits the INTERNAL balance and sends the ticket webhooks, exactly as it would for a real transfer.

info

This endpoint exists only in sandbox. In production the deposit comes from a real SWIFT transfer sent to the account's swiftReceivingAccount, and the same ticket, webhooks and credit follow.

Before you start

The account needs SWIFT deposits enabled. Ask your account manager to enable them for your sandbox account. Once they are, GET /v2/account/account-info returns a swiftReceivingAccount object. See Static Deposits.

1. Read the receiving account

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/account-info" \
  -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON
{
  "swiftReceivingAccount": {
    "beneficiaryName": "Jane Doe",
    "bankName": "Sandbox Bank",
    "bic": "SBXXUS33XXX",
    "accountNumber": "9999000123456789",
    "routingNumber": "999999999",
    "bankAddress": {
      "street1": "1 Sandbox Plaza",
      "street2": "",
      "city": "New York",
      "region": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  }
}

In sandbox these are test details no real bank can pay. Show them the way you will show the real ones in production.

2. Simulate the transfer

POSThttps://api.sandbox.avenia.io:10952/v2/account/sandbox/swift-deposits

Parameters

Field	In	Type	Description
`subAccountId`	query	string	Optional. The sub-account that receives the deposit. Omit it for the main account.

Body

Field	Type	Required	Description
`amount`	string	Yes	The USD that arrives, as a decimal string with at most two decimals, such as `"150.00"`.
`senderName`	string	No	The sender's name, as the sender's bank reports it. Omit it for a transfer from the account holder.
`senderType`	string	No	`individual` or `business`. Defaults to `individual`.
`senderBankName`	string	No	The sender's bank.
`senderAccountNumber`	string	No	The sender's account number or IBAN.
`senderBic`	string	No	The sender's bank BIC.
`paymentReference`	string	No	The reference the sender wrote on the transfer.

Request example

cURL
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/sandbox/swift-deposits" \
  -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "150.00",
    "senderBankName": "Example Bank",
    "paymentReference": "INVOICE-1042"
  }'

Response

202 Accepted. The deposit is processed in the background.

JSON
{
  "id": "sbxtx3f1c2a7e5b8d4e6f9a0b1c2d3e4f5a6b"
}

id is the simulated deposit. Every call is a new transfer: calling twice simulates two deposits.

3. Follow the ticket

Avenia creates the deposit's ticket by itself within seconds of the call. You receive the ticket webhooks for it, as for a real SWIFT deposit: DEPOSIT-PROCESSING, DEPOSIT-SUCCESS, DELIVERY-PROCESSING, DELIVERY-SUCCESS, TICKET-PURPOSE-CODE-REQUIRED and TICKET-COMPLETE. They can arrive in a different order. See Webhook Events and When Avenia asks for the code afterwards.

To find the ticket without a webhook, list the tickets by its externalId, which is swift-deposit- followed by the id the call returned:

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/tickets/?externalId=swift-deposit-sbxtx3f1c2a7e5b8d4e6f9a0b1c2d3e4f5a6b" \
  -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

The ticket has inputCurrency USD, inputPaymentMethod SWIFT, outputCurrency USDC and outputPaymentMethod INTERNAL, and ends PAID with the USDC credited to the account's INTERNAL balance.

Simulating a third-party sender

Send a senderName that is not the account holder's name to simulate a transfer from someone else:

cURL
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/sandbox/swift-deposits" \
  -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "80.00",
    "senderName": "Example Trading Inc",
    "senderType": "business",
    "senderBic": "EXAMPLEXXXX"
  }'

It is a third-party deposit and is priced as one. When the account doesn't accept third-party deposits, it is held for compliance review instead of being credited, as in production. See USD by SWIFT.

Errors

Status	Message	Meaning
`400`	`SWIFT deposits are not enabled for this account`	The account has no SWIFT receiving account yet. See Before you start.
`400`	`InvalidFieldError: amount is invalid`	The amount is missing, not a number, not positive, or has more than two decimals.
`400`	`InvalidFieldError: senderType is invalid`	`senderType` is neither `individual` nor `business`.

What is not simulated

These behave exactly as in production:

The account's limits: a deposit over the monthly fiat-in limit for USD is not credited.
The fees and the quote of the conversion to USDC.
The comparison of the sender with the account holder.

If any of these return an unexpected result in sandbox, it reflects a real behavior, not the simulation.

Before you start​

1. Read the receiving account​

2. Simulate the transfer​

Parameters​

Body​

Request example​

Response​

3. Follow the ticket​

Simulating a third-party sender​

Errors​

What is not simulated​