Save Transaction

When to use it: Use this webhook to register a new incoming payment/transaction into a merchant account.

webhookType: SAVE_TRANSACTION

When working with transactions, it is essential to use a common identifier to link multiple transactions associated with a single expense. To achieve this, ensure that the orderId field within the SAVE_TRANSACTION webhook contains the same unique value for all related transactions, such as reserve transactions, accepted transactions, and others.

For a proper categorisation of the transactions, make sure you are identifying the different fields, by looking at the Mapping and Enums documentation, paying special attention to the logic affecting the fields Pay type and Transaction type .

See all available transaction statuses

Dynamic fields

If you would like to display any additional information related to a transaction, you can pass this information using **dynamicFields** field.

Transaction title

Transaction title is used to identify the key description or label associated with a transaction. It helps users quickly understand the nature of the transaction. You can define your own transaction title or use Toqio default values. By default, the transaction title is populated with specific data based on Pay type The following rules apply:

Card Transaction:
- Refund: The title is set to a static text value, "Refund - [merchant]", where [merchant] is the merchant field data. This title can be overridden if a custom title is provided by the system integrator.
- All Other Transaction Types: The title is populated with the merchant field name.
Inbound Transactions:
- Refund: The title is set to "Refund - [source account name]," where [source account name] refers to the originating account. This can also be overridden by a custom title provided by the system integrator.
- All Other Transaction Types: The title is populated with the sourceAccount name.
Outbound Transactions: the title is populated with the destinationAccount name.
Manual Transactions: the title is populated with the merchant field.

Request Body per Pay Type

When sending the "Save Transaction" webhook, the required minimum fields vary depending on the pay type.

CARD: This type represents transactions made using debit cards

CARD
{
    "id": "uuid",
    "user": "string",
    "company": "string", //mandatory
    "customer": "string",// mandatory
    "clientType": "BUSINESS | CONSUMER", //mandatory
    "type": "EXPENSE | PAYMENT | INBOUND | REFUND", //mandatory
    "status": "FAILED | PENDING | ACCEPTED | CANCELLED",// mandatory
    "currency": "string", //mandatory
    "baseCurrency": "string", //mandatory
    "total": "number (double)",// mandatory
    "baseTotal": "number (double)", //mandatory
    "transactionNumber": "string", //mandatory
    "merchant": "string",
    "address": "string",
    "payType": "CARD | INBOUND_BANK_TRANSFER | OUTBOUND_BANK_TRANSFER", //mandatory
    "date": "string (date)",//mandatory
    "sourceAccount": { //mandatory
        "id": "uuid",
        "type": "AUD | CHF | CAD | SEK | GOLDBLOC | USD | NOK | WHISKY | JPY | NZD | GOLD | GBP | EUR | CZK | DKK | HUF | PLN | RON | ILS | RUB | BHD | SAR | BGN | KES | SGD | KWD | ZAR | CNY | MYR | HRK | MXN | THB | TRY | OMR | UGX | HKD | PHP | AED | INR | QAR | IDR | POINTS",
        "name": "string",
        "iban": "string",
        "bicSwift": "string",
        "ukAccountNumber": "string",
        "ukSortCode": "string",
        "accountNumber": "string",
        "routingNumber": "string",
        "caRoutingNumber": "string",
        "address": "string",
        "address2": "string",
        "city": "string",
        "postalCode": "string",
        "countryCode": "string"
    },
    "balance": "number (double)", //mandatory
    "country": "string", 
    "corePaymentType": "payment-type-Global-SWIFT | payment-type-UK-BACS | payment-type-EU-SEPA-Target2 | payment-type-UK-Chaps | payment-type-EU-SEPA-Step2 | payment-type-virtual-debit-card-debit | payment-type-inter-ledger | payment-type-UK-FasterPayments | payment-type-fx | payment-type-card | payment-type-card-reserve | payment-type-EU-SEPA-Instant | payment-type-AU-NPP | payment-type-EU-Target2 | payment-type-AU-DE | payment-type-US-ACH | payment-type-SG-FAST | payment-type-US-Wires | SPEI | AUS-PAY-NET | EFT | NCS | CERTIS | STRAKSCLEARING-Instant | INTRADAGCLEARING | CHATS | GIRO_ZRT | IMPS | NEFT | SKN | IBG | NORWEGIAN-INTERBANK-CLEARING-SYSTEM | PESONET | ELIXIR | TRANSFOND_SENT_ACH | FAST | INTERNAL-TRANSFER | RIX | FEDACH | FEDWIRE | CHIPS | SEPA | TARGET2 | DIRECT_DEBIT_OUTBOUND", //mandatory
    "bankName": "string", //mandatory
    "bankLogo": "string",
    "bankDescription": "string", //mandatory
    "failureReason": "string",
    "finalTxNumber": "string",
    "cardId": "string",
    "orderId": "string",
    "ledgerType": "string",
    "dynamicFields" : [{
        "label": {"en":"string", "es":"string", "xh":"string"},
        "valueId": "string",
        "value": "string"
    }],
    "emails": ["string"],
    "advancedInvoiceId":"string",
    "transactionTitle":"string",
    "card":"string",
    "cardId":"string",//mandatory
    "txFee":"string",
    "cardTransactionType":"string"
}

INBOUND_BANK_TRANSFER: This type signifies funds received through bank transfers.

INBOUND_BANK_TRANSFER
{
    "id": "uuid",
    "user": "string",
    "company": "string", //mandatory
    "customer": "string", //mandatory
    "clientType": "BUSINESS | CONSUMER", //mandatory
    "type": "EXPENSE | PAYMENT | INBOUND | REFUND", //mandatory
    "status": "FAILED | PENDING | ACCEPTED | CANCELLED", //mandatory
    "currency": "string",// mandatory
    "baseCurrency": "string",// mandatory
    "total": "number (double)",// mandatory
    "baseTotal": "number (double)",// mandatory
    "transactionNumber": "string", //mandatory
    "merchant": "string",
    "address": "string",
    "payType": "CARD | INBOUND_BANK_TRANSFER | OUTBOUND_BANK_TRANSFER", //mandatory
    "date": "string (date)",//mandatory
    "sourceAccount": { //mandatory
        "id": "uuid",
        "type": "AUD | CHF | CAD | SEK | GOLDBLOC | USD | NOK | WHISKY | JPY | NZD | GOLD | GBP | EUR | CZK | DKK | HUF | PLN | RON | ILS | RUB | BHD | SAR | BGN | KES | SGD | KWD | ZAR | CNY | MYR | HRK | MXN | THB | TRY | OMR | UGX | HKD | PHP | AED | INR | QAR | IDR | POINTS",
        "name": "string",
        "iban": "string",
        "bicSwift": "string",
        "ukAccountNumber": "string",
        "ukSortCode": "string",
        "accountNumber": "string",
        "routingNumber": "string",
        "caRoutingNumber": "string",
        "address": "string",
        "address2": "string",
        "city": "string",
        "postalCode": "string",
        "countryCode": "string"
    },
    "balance": "number (double)", //mandatory
    "country": "string", 
    "corePaymentType": "payment-type-Global-SWIFT | payment-type-UK-BACS | payment-type-EU-SEPA-Target2 | payment-type-UK-Chaps | payment-type-EU-SEPA-Step2 | payment-type-virtual-debit-card-debit | payment-type-inter-ledger | payment-type-UK-FasterPayments | payment-type-fx | payment-type-card | payment-type-card-reserve | payment-type-EU-SEPA-Instant | payment-type-AU-NPP | payment-type-EU-Target2 | payment-type-AU-DE | payment-type-US-ACH | payment-type-SG-FAST | payment-type-US-Wires | SPEI | AUS-PAY-NET | EFT | NCS | CERTIS | STRAKSCLEARING-Instant | INTRADAGCLEARING | CHATS | GIRO_ZRT | IMPS | NEFT | SKN | IBG | NORWEGIAN-INTERBANK-CLEARING-SYSTEM | PESONET | ELIXIR | TRANSFOND_SENT_ACH | FAST | INTERNAL-TRANSFER | RIX | FEDACH | FEDWIRE | CHIPS | SEPA | TARGET2 | DIRECT_DEBIT_OUTBOUND", //mandatory
    "bankName": "string", //mandatory
    "bankLogo": "string",
    "bankDescription": "string",// mandatory
    "failureReason": "string",
    "finalTxNumber": "string",
    "cardId": "string",
    "orderId": "string",
    "ledgerType": "string",
    "dynamicFields" : [{
        "label": {"en":"string", "es":"string", "xh":"string"},
        "valueId": "string",
        "value": "string"
    }],
    "emails": ["string"],
    "advancedInvoiceId":"string",
    "transactionTitle":"string",
    "destinationAccount"://mandatory
    {
        "id": "string",
        "type": "gbp | eur | aud | chf | cad | sek | usd | points | nok | jpy | sgd | nzd | czk | dkk | huf | pln | ron | ils | rub | bhd | sar | bgn | kes | kwd | zar | cny | myr | hrk | mxn | thb | try | omr | ugx | hkd | php | aed | inr | qar | idr",
        "name": "string",
        "iban": "string",
        "bicSwift": "string",
        "ukAccountNumber": "string",
        "ukSortCode": "string",
        "routingNumber": "string",
        "caRoutingNumber": "string",
        "accountNumber": "string",
        "bsbCode": "string",
        "address": "string",
        "address2": "string",
        "city": "string",
        "postalCode": "string",
        "countryCode": "string",
        "main": true,
        "bankingProvider": "string",
        "ledgerType": "string"
      },
    "concept":"string"//mandatory

}

OUTBOUND_BANK_TRANSFER: This type denotes funds sent through bank transfers.

OUTBOUND_BANK_TRANSFER
{
    "id": "uuid",
    "user": "string",
    "company": "string", //mandatory
    "customer": "string", //mandatory
    "clientType": "BUSINESS | CONSUMER", //mandatory
    "type": "EXPENSE | PAYMENT | INBOUND | REFUND", //mandatory
    "status": "FAILED | PENDING | ACCEPTED | CANCELLED", //mandatory
    "currency": "string", //mandatory
    "baseCurrency": "string", //mandatory
    "total": "number (double)", //mandatory
    "baseTotal": "number (double)", //mandatory
    "transactionNumber": "string", //mandatory
    "merchant": "string",
    "address": "string",
    "payType": "CARD | INBOUND_BANK_TRANSFER | OUTBOUND_BANK_TRANSFER", //mandatory
    "date": "string (date)",//mandatory
    "sourceAccount": { //mandatory
        "id": "uuid",
        "type": "AUD | CHF | CAD | SEK | GOLDBLOC | USD | NOK | WHISKY | JPY | NZD | GOLD | GBP | EUR | CZK | DKK | HUF | PLN | RON | ILS | RUB | BHD | SAR | BGN | KES | SGD | KWD | ZAR | CNY | MYR | HRK | MXN | THB | TRY | OMR | UGX | HKD | PHP | AED | INR | QAR | IDR | POINTS",
        "name": "string",
        "iban": "string",
        "bicSwift": "string",
        "ukAccountNumber": "string",
        "ukSortCode": "string",
        "accountNumber": "string",
        "routingNumber": "string",
        "caRoutingNumber": "string",
        "address": "string",
        "address2": "string",
        "city": "string",
        "postalCode": "string",
        "countryCode": "string"
    },
    "balance": "number (double)", //mandatory
    "country": "string", 
    "corePaymentType": "payment-type-Global-SWIFT | payment-type-UK-BACS | payment-type-EU-SEPA-Target2 | payment-type-UK-Chaps | payment-type-EU-SEPA-Step2 | payment-type-virtual-debit-card-debit | payment-type-inter-ledger | payment-type-UK-FasterPayments | payment-type-fx | payment-type-card | payment-type-card-reserve | payment-type-EU-SEPA-Instant | payment-type-AU-NPP | payment-type-EU-Target2 | payment-type-AU-DE | payment-type-US-ACH | payment-type-SG-FAST | payment-type-US-Wires | SPEI | AUS-PAY-NET | EFT | NCS | CERTIS | STRAKSCLEARING-Instant | INTRADAGCLEARING | CHATS | GIRO_ZRT | IMPS | NEFT | SKN | IBG | NORWEGIAN-INTERBANK-CLEARING-SYSTEM | PESONET | ELIXIR | TRANSFOND_SENT_ACH | FAST | INTERNAL-TRANSFER | RIX | FEDACH | FEDWIRE | CHIPS | SEPA | TARGET2 | DIRECT_DEBIT_OUTBOUND", //mandatory
    "bankName": "string", //mandatory
    "bankLogo": "string",
    "bankDescription": "string", //mandatory
    "failureReason": "string",
    "finalTxNumber": "string",
    "cardId": "string",
    "orderId": "string",
    "ledgerType": "string",
    "dynamicFields" : [{
        "label": {"en":"string", "es":"string", "xh":"string"},
        "valueId": "string",
        "value": "string"
    } ],
    "emails": ["string"],
    "advancedInvoiceId":"string",
    "transactionTitle":"string",
    "txFee":"string",
    "fxRate":"string",
    "fixedSide":"string",
    "beneficiaryCurrencyAmount":"string",
    "reference":"string",
    "paymentProviderDetails":"string",
    "postingDate":"string",
    "settlementDate":"string",
    "mandateId":"string",
    "frequency":"string",//mandatory
    "destinationAccount": //mandatory
    {
        "id": "string",
        "type": "gbp | eur | aud | chf | cad | sek | usd | points | nok | jpy | sgd | nzd | czk | dkk | huf | pln | ron | ils | rub | bhd | sar | bgn | kes | kwd | zar | cny | myr | hrk | mxn | thb | try | omr | ugx | hkd | php | aed | inr | qar | idr",       "name": "string",
        "iban": "string",
        "bicSwift": "string",
        "ukAccountNumber": "string",
        "ukSortCode": "string",
        "routingNumber": "string",
        "caRoutingNumber": "string",
        "accountNumber": "string",
        "bsbCode": "string",
        "address": "string",
        "address2": "string",
        "city": "string",
        "postalCode": "string",
        "countryCode": "string",
        "main": true,
        "bankingProvider": "string",
        "ledgerType": "string"
      },
    "concept":"string",//mandatory
}

EXAMPLE

{
  "id": "c14a080d-7bd3-4bab-8e2f-1d71a0123e5f",
  "user": "John Doe",
  "company": "ABC Inc.",
  "customer": "Jane Smith",
  "clientType": "BUSINESS",
  "type": "EXPENSE",
  "status": "ACCEPTED",
  "currency": "USD",
  "baseCurrency": "USD",
  "total": 250.75,
  "baseTotal": 250.75,
  "transactionNumber": "TXN123456",
  "merchant": "Office Depot",
  "address": "123 Main St",
  "payType": "OUTBOUND_BANK_TRANSFER",
  "date": "2024-06-27",
  "sourceAccount": {
    "id": "60d7f7a3f163b41f94f89c24",
    "type": "USD",
    "name": "Primary Account",
    "iban": "GB29NWBK60161331926819",
    "bicSwift": "NWBKGB2L",
    "ukAccountNumber": "41495926",
    "ukSortCode": "601613",
    "accountNumber": "1234567890",
    "routingNumber": "021000021",
    "caRoutingNumber": "123456789",
    "address": "456 Elm St",
    "address2": "",
    "city": "London",
    "postalCode": "SW1A 1AA",
    "countryCode": "GB"
  },
  "balance": 5000.25,
  "country": "UK",
  "corePaymentType": "payment-type-UK-BACS",
  "bankName": "New Bank",
  "bankLogo": "https://example.com/bank-logo.png",
  "bankDescription": "A new bank for the future",
  "failureReason": "",
  "finalTxNumber": "FINAL123",
  "cardId": "",
  "orderId": "ORDER987654",
  "ledgerType": "BANK_TRANSFER",
  "dynamicFields": [
    {
      "label": {
        "en": "Payment Reference",
        "es": "Referencia de pago",
        "xh": "Isalathisi yokuhlawula"
      },
      "valueId": "reference123",
      "value": "REF0012345"
    }
  ],
  "emails": ["[email protected]"],
  "advancedInvoiceId": "ADV987654",
  "transactionTitle": "Office Supplies Payment",
  "destinationAccount": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "USD",
    "name": "Business Account",
    "iban": "US98765432109876543210",
    "bicSwift": "NEWBGB2L",
    "ukAccountNumber": "98765432",
    "ukSortCode": "987654",
    "routingNumber": "021000021",
    "caRoutingNumber": "987654321",
    "accountNumber": "1234567890",
    "bsbCode": "987-654",
    "address": "789 Corporate Blvd",
    "address2": "Suite 200",
    "city": "Manchester",
    "postalCode": "M1 1AA",
    "countryCode": "GB",
    "main": true,
    "bankingProvider": "BankCorp",
    "ledgerType": "TRANSFER"
  },
  "concept": "Payment for office supplies"
}