Payment

Definition

Swan provides the following payment methods:

  • credit transfer

  • direct debit

  • payment cards

A payment can be initiated by:

  • a Swan app user

  • a merchant

  • you

  • Swan

"A Payment" comprises all transactions linked to one initiated payment.

Example:

The user initiates a SEPA Credit Transfer of €152,45 towards an IBAN.

1st transaction: the SEPA Credit Transfer is sent on the SEPA network.

2nd transaction: the financial institution returns the money because the IBAN doesn't exist.

Accounts at Swan were designed to never go below zero. In fact, payments will be refused if the Account's available balance is not sufficient to cover the total payment amount.

Credit Transfer

Sepa Credit Transfer

SEPA Credit Transfer (SCT) lets you transfer euros between accounts situated in the SEPA zone (all EU countries + the UK, Iceland, Lichtenstein, Norway, and Switzerland).

When an account receives a SEPA Credit Transfer, the transaction will be the SepaCreditTransferIntype.

When an account issues a SEPA Credit Transfer, the transaction will be the SepaCreditTransferOuttype.To validate the provided IBAN in the SCT out we execute multiple checks :

  • Is the IBAN size greater or equal to five?

  • Are the third and fourth characters numeric?

  • Is the country code an existing one?

  • Does the IBAN size match the country's IBAN size?

  • Is the IBAN checksum correct?

Be careful, when the Account holder verification process has not yet been completed by Swan and the Account has paymentLevel=Limited, the only possible beneficiary of SCT out is the Account holder's IBAN in another establishment.

Internal Credit Transfer

When an Account receives an internal transfer, the transaction will be the InternalTransferIn type.

When an Account issues an internal transfer, the transaction will be the InternalTransferOuttype.

Careful, when the Account owner's KYC has not yet been completed, it has not yet been accepted by Swan, and the Account will have the paymentLevel=Limited status. This means transfers are limited to 150€ over a period of 30 days and are only allowed for purchasing goods and services for consumption.

Beneficiary

You can create a list of trusted beneficiaries for an Account.

To add or remove a beneficiary the Account membership must have the canManageBeneficiaries right.

With this list you can:

  • Relax consent requests to offer a more streamlined user experience.

  • Allow users to initiate payments even if they don't have the right to add beneficiaries. Just use the canInitiatePayments right.

When added to this list, the Account holder can inform Swan via the isMyOwnIBAN field that the IBAN of another financial establishment also belongs to him. Once verified by Swan's anti-fraud team, the account holder just has to perform consent with Swan app to be allowed to initiate payments towards this beneficiary. This is super useful if your customer wants to collect payments on a Swan account and have them regularly sent back to their primary account in another financial institution without having to be solicited for every single transfer.

Initiate Credit Transfers

You can initiate credit transfers (Internal or SEPA) :

  • #nocode: use the white-labeled Web banking; the deeplink URL is available in your dashboard under the tab White-label #nocode.

  • by API: integrate payments into your product using our API.

To initiate credit transfers by API you must use the initiateCreditTransfer **** mutation. Make sure you are authentified with an accessToken in the name of the user that wants to make the payment. Learn More.

With just one call to this mutation you can initiate multiple credit transfers from the same account, towards different accounts, and for different amounts. Take note: this allows to make just one consent request for multiple transactions. This is helpful for setting up monthly payroll, or paying weekly bills.

You can add a new beneficiary to the list of trusted beneficiaries by setting the save field to true. This keeps you from having to solicit user consent twice in a row (once for adding the beneficiary, and again for initiating payment).

A request from theinitiateCreditTransfermutation has two possible returns:

  1. Swan requests user consent. In this case, the payment is created with ConsentPending status and a newly created consent resource carrying the consentUrl redirects the user to launch Swan app's Strong Customer Authentication. Learn More. Once the consent process and Strong Customer Authentication is completed, the payment changes to Initiatedstatus.

  2. Swan estimates that the context of this payment doesn't require user consent. In this case, the payment is created with Initiatedstatus.

Once the consent process and Strong Customer Authentication is completed, Swan checks that the available balance is sufficient to cover the total payment amount. If this is the case, a paymentProduct=SepaCreditTransfer transaction is created with Pendingstatus. This will change to Booked status once the transaction is approved by Swan's financial security.

If the amount is insufficient, a transaction is created with Rejected status, with the reason for rejection in the rejectedReasonCodefield.

R-Transactions

Once a credit transfer is initiated, there can be other transactions for the same payment linked to exterior events.

Return

When an issued payment is returned because the account doesn't exist, or is closed, or for whatever reason won't receive the payment, a second transaction is created with the SepaCreditTransferOutReturn type to credit the account.

When a credit transfer that has already been received and credited to the account is refused by the account owner, a second transaction is created with the SepaCreditTransferInReturn type to debit the account.

To simulate these exterior events in the Sandbox we have added the tab Event Simulator to your dashboard. It lets you test different scenarios.

Recall

When a user asks Swan to recall a credit transfer that was issued by error Swan transfers this request to the financial establishment that received the transfer so that they can solicit the beneficiary and ask if they accept the recall of this transfer. If the beneficiary accepts, a second transaction is created with the SepaCreditTransferOutRecall type to credit the account.

When the issuer of a credit transfer towards a Swan account asks his financial institution to recall a transfer issued by mistake the Financial establishment transmits this request to Swan so they can solicit the account holder and ask if he accepts the recall of this transfer. If they accept, a second transaction is created with the SepaCreditTransferInRecall type to debit the account.

To simulate these exterior events in the Sandbox we have added the tab Event Simulator to your dashboard. It lets you test different scenarios.

Direct Debit

Sepa Direct Debit

SEPA Direct Debit (SDD) lets you issue direct debit in euros between accounts situated in the SEPA zone.

This payment method lets a merchant debit an Account after having had its account holder sign a direct debit mandate. Handling the direct debit mandate is the responsibility of the merchant who is identified by a Unique Mandate Reference (UMR). The merchant is identified on the SEPA network with a SEPA creditor identifier (SCI). The coupling of SCI and UMR is unique.

There are 2 types of SEPA Direct Debit:

  • The SDD Core is the most widely used and can be used to debit an account belonging to natural or legal persons. The SDD Core gives a debtor the right to reimbursement within 8 weeks without justification and 13 months in the case of a missing mandate. The transactions linked to SDD Core have the paymentProduct=SepaDirectDebitCorevalue.

To see if it's SDD core you see in the field:

  • The SDD B2B (business to business) can only be used by legal persons. Swan must check with the account holder that the mandate is valid before being able to initiate payments by SDDB2B. In fact, they must have previously declared the SDD B2B mandate references for which they authorize payments because this represents the account holder’s consent to settle a debt by SDD B2B and stipulates the absence of a right to reimbursement of the debtor. The transactions linked to SDD B2B have the paymentProduct=SepaDirectDebitB2B value.

To be acknowledged by the SEPA network, a Direct Debit request must be received between 1-15 days from Direct Debit date requested by the merchant. Once received by Swan, there are 2 possibilities:

  • If the mandate is Suspended or Canceled or if it's a SDD B2B and the mandate doesn't exist, then a transaction with theSepaDirectDebitOuttype and Rejected status is created with the rejection reason in therejectedReasonCode field.

  • If a mandate already exists with Enabled status if it's a SDD Core and a new mandate, a transaction with the SepaDirectDebitOut type and Upcoming status is created. This will be executed on the chosen execution date.

On the day of the Direct Debit's execution, Swan checks that the Available Balance of the account is sufficient to cover the total payment amount:

  • If it is not sufficient, a transaction with theSepaDirectDebitOut type and Rejected status is created with the rejection reason in the rejectedReasonCode field.

  • If it is sufficient, a transaction with the SepaDirectDebitOut type and Booked status is created.

Internal Direct Debit

Coming soon ...

Mandate

Mandates are mandatory with a Direct Debit payment. They represent an account holder's authorization to make Direct Debits to the merchant. A mandate is linked to an account.

There are different types of Mandates:

  • SepaCore : this one is used for SEPA Direct Debit Core. It is created at Swan during a first Direct Debit request.

  • SepaB2B : this one is used for SDD B2B. It must be declared in advance for the Direct Debit to work. To do this, you must call the createB2BMandatemutation. The mandate is immediately created with the ReviewPending status so that Swan's financial security can give its approval to use this B2B mandate. Once accepted, the mandate changes to Enabledstatus. If it's refused, it changes to Rejectedstatus.

  • Internal : coming soon !

You can suspend a mandate by calling the suspendMandatemutation. Once executed, Swan will systematically reject Direct Debits for this mandate. ****

You can reactivate a mandate by calling the resumeMandate mutation. Once executed, Swan will no longer systematically reject Direct Debits for this mandate.

You can definitively cancel a mandate by calling the cancelMandatemutation**.** Once executed, all Direct Debits for this mandate will be definitively rejected.

R-Transactions

In some cases, you can receive reimbursements from a Direct Debit.

When a physical person executes a Direct Debit, the law imposes that the account holder be able to contact Swan by email to request a reimbursement. They can do this up to 8 weeks after execution without justification, or up to 13 months if a mandate is missing.

It also happens that merchants cancel their Direct Debit due to error or duplicate entry.

In all cases, a new transaction with theSepaDirectDebitOutRefund type is created with Bookedstatus.

To simulate these exterior events in the Sandbox environment, we have added an Event Simulator tab to your dashboard. It lets you test different scenarios.

Card

There are two steps to managing card payments:

  • Authorization: allowing a merchant to verify, in real-time, that the payer really has the authorization to make the payment (security features are respected, there is sufficient available balance, active card status, spending limits haven't been exceeded...) This can be online or offline depending on the payment terminal.

  • Clearing: allowing the merchant to ask, asynchronously, for debit or credit on a card.

The transaction object contains a specialized CardTransactioninterface featuring the specific payment data per card such as:

  • Terminal ID: unique identifier of the terminal in the Mastercard network

  • Merchant ID: unique identifier of the merchant in the Mastercard network

  • Merchant Name

  • Merchant City

  • Merchant Category Code (MCC)

  • Original Amount and Currency

Authorization

ONLINE

When a card holder makes a payment with their card, the majority of payment terminals make an authorization request online.

If the authorization is refused a transaction of CardOut type is created with the refused status and the reasonCode describing the reason for the refusal.

On the other hand, when if the authorization is accepted, a transaction of CardOut type is created with pending status, and the available balance of the account is impacted.

In some cases, such as fuel distributors, an authorization can be partial. In fact, if the merchant asks for 120€ while the available account balance is only 55€, Swan can accept the authorization for just 55€.

Sometimes, an authorization can also be updated at a later time. In fact, the fuel distributor could have received authorization for 55€ but the moment the client hangs up the nozzle, the authorization is updated to 24€, corresponding to the amount actually consumed. In this case, the amount of the transaction with pending status is updated and the amount that is no longer authorized is free from the available balance.

An authorization is not valid forever, we've decided to wait for a clearing of between 10 to 30 days depending on the type of business before expiring the transaction. The expiration date is in the pendingEndDate field of the PendingTransactionStatusInfo object describing the pending status of a transaction.

Once an authorization is expired, the available balance that has not been debited is free from the available account balance and the transaction is updated with a status released

All transactions linked to an authorization are linked by the same payment: authorization, debits, credits, chargeback.

To simulate these exterior events in the Sandbox we have added the tab Event Simulator to your dashboard. It lets you test different scenarios.

The Mastercard network always requires Swan to either approve or deny transactions. With the Payment control feature, you are brought into the process. Payment Control allows you to approve or deny every single card transaction. More details here.

OFFLINE

It can happen that some payment terminals in physical sales points are not able to carry out authorizations online (parking, tolls, planes, trains, network failure, ...). In this case, the payment can still be accepted offline in the limit of an amount defined by Swan depending on the account holder's risk level.

In this case, the payment is still taken into account by Swan at the moment of clearing without having to use the online authorization process.

Clearing

DEBIT

When a merchant requests debit on a card, Swan receives the information asynchronously and creates a new transaction of CardOut type debit with booked status that impacts the account's booked balance.

If a debit transaction is linked to an authorization, the transaction with pending status corresponding to this authorization is updated with the remaining amount to be debited. If the amount of this transaction is ≤ 0, the status released is applied.

It's possible to have one or several partial debits on an authorization. Example: a client buys 2 products for 150€ at an online shop, the first product worth 50€ is shipped but the second of 100€ is out of stock. The first transaction of 150€ with pending status is updated to 100€ and a new transaction is created with booked status for an amount of 50€ .

Watch out, it's also possible to be debited more than the amount initially authorized.

To simulate these exterior events in the Sandbox we have added the tab Event Simulator to your dashboard. It lets you test different scenarios.

CREDIT

When a merchant requests credit on a card, Swan receives the information asynchronously and creates a new transaction with CardRefund type of credit with booked status that impacts the account's booked balance.

If a credit intervenes following a debit, the 2 transactions will be linked to the same payment.

To simulate these exterior events in the Sandbox we have added the tab Event Simulator to your dashboard. It lets you test different scenarios.

Chargebacks

When a client is a victim of fraud, they must declare it to Swan. If after an investigation by our fraud team, the chargeback is admissible, a new credit transaction of CardChargeback type with booked status is created and will impact the account's booked balance.

The transaction of the chargeback is linked to the same payment as the transaction of the initial debit.

To simulate these exterior events in the Sandbox we have added the tab Event Simulator to your dashboard. It lets you test different scenarios.