Links

Payment control

Introduction

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.
When activated, Swan will send you the transaction details received by Mastercard and take your answer into account. We'll do our own tests (does the card and account exist? are there enough funds?), if everything is OK on our side, we'll take your answer into account. Only then do we answer Mastercard. Beware that we do our control at the same time as we send you the request, so even if you accept a payment, we can refuse it.
Time is very sensitive in this operation. A timeout from Swan will result in a declined operation for the cardholder. Therefore, you'll want to test this feature thoroughly. We provide all the materials you need to test in our sandbox, including the ability to set a default answer in case of timeout.
Transaction flow

Add a payment control endpoint

The updateCardPartnerControlmutation is used to set up and update the payment control. Here are the available settings:
  • endpoint: your endpoint (mandatory)
  • protocol: for now, it must be HttpJson
  • defaultResponse: in case of timeout, can be true or false
  • timeoutMs: to allow you more flexibility, up to 10s in the sandbox environment and 1,5s in the live environment.
  • secret: we'll add your secret to a "x-swan-secret" header

Transaction data sent

We add flags to specify that Swan is making the POST request :
  • An "x-swan" http header
  • An "x-swan-secret" http header with the provided secret
The payload is as follows. All fields are optional as they are subject to changes:
Payload
Response
1
{
2
"timeoutAt": 1646214666661, //fallback time to default response
3
"transactionId": "{{TRANSACTION_ID}}",
4
"paymentId": "{{PAYMENT_ID}}",
5
"accountId": "{{PAYMENT_ID}}",
6
"cardId": "{{CARD_ID}}",
7
"digitalCardWalletProvider": "ApplePay", //digital token used for transaction; ApplePay, GooglePay, Merchant
8
"dateTime": 1646214656661, //time payment occured
9
"expirationDateTime": 1647114656661, //time authorization will be released if preauthorized amount is not used
10
"originalAmountValue": 10.00,
11
"originalAmountCurrency": "EUR",
12
"amountValue": 10.00,
13
"amountCurrency": "EUR",
14
"merchantId": "SWAN",
15
"terminalId": "156428",
16
"merchantCategoryCode": "0000",
17
"merchantName": "SWAN",
18
"merchantCity": "PARIS",
19
"merchantPostalCode": "75010", //optional information
20
"merchantCountry": "FRA",
21
"readMode": "Chip", //Chip, ContactlessChip, ContactlessStripe, Manual, ManualChip, ManualStripe, Other, PreSavedData, Stripe
22
"transactionCategory": "InStore", //InStore, eCommerce, eCommerceWith3DS, Withdrawal, Other
23
"authorizationType": "Classic", //Classic, PreAuthorization, DataRequest
24
"allowsPartialAuthorization": true //if amount can be modified
25
}
  • Lines 2, 8-9: All times are written in epoch millis.
  • Line 7: Per your and Swan's agreement with Mastercard, you cannot reject transactions based on digital wallet provider.
{
"accepted": true,
"partialAuthorizationAmountValue": 10
}

Your answer

As an answer, we expect a boolean in the accepted field. If the authorization allows a partial hold of the funds, you can also lower the initial amount by providing the amount you want to send back to the merchant. We'll take your default response into account if we don't have an answer from you after the timeout or endpoint contact error.
We suggest a default response true from a client perspective.
It could happen that both of our answers (yours and Swan's) aren't accepted by Mastercard due to QoS and delegation process