Card transactions

Whenever a purchase is made with a card, a corresponding transaction is sent to the integrating Partner. This requires that an endpoint is made available on the Partner side to which incoming transactions can be posted.

Example of a reserved transaction:

{
  "id": "d6a38749-c6fd-5d98-a91b-b03d02f70ffb",
  "rev": 2,
  "status": "RESERVED",
  "companyId": "25d524a8-d476-4dc5-9291-3bd5f7fdb1fb",
  "companyExternalId": "123",
  "personId": "baf1ceb0-f1da-4945-9fe1-0b7364da9c79",
  "personExternalId": "2",
  "cardId": "df902530-ba74-4726-9a3f-953c56fb170f",
  "lastFourDigits": "4190",
  "date": "2024-01-10T09:49:29.807799966",
  "settlementDate": null,
  "totalAmount": {
    "value": -436.65,
    "currency": "SEK"
  },
  "originalAmount": null,
  "name": "Dodeli",
  "city": "FAKE CITY",
  "country": "SE",
  "mcc": "5813",
  "responseCode": "00",
  "responseCodeDescription": "Approved or completed successfully",
  "fileHandles": [],
  "sourceInvoiceId": null
}

‍

Example of a settled transaction:

{
  "id": "b472bb3d-313e-50a2-9321-d8add43cb44b",
  "rev": 4,
  "status": "SETTLED",
  "companyId": "25d524a8-d476-4dc5-9291-3bd5f7fdb1fb",
  "companyExternalId": "123",
  "personId": "baf1ceb0-f1da-4945-9fe1-0b7364da9c79",
  "personExternalId": "2",
  "cardId": "df902530-ba74-4726-9a3f-953c56fb170f",
  "lastFourDigits": "4190",
  "date": "2023-11-24T12:07:25.952321127",
  "settlementDate": "2023-11-24",
  "totalAmount": {
    "value": -169.04,
    "currency": "SEK"
  },
  "originalAmount": null,
  "name": "Honest no Thanks",
  "city": "FAKE CITY",
  "country": "SE",
  "mcc": "5813",
  "responseCode": "00",
  "responseCodeDescription": "Approved or completed successfully",
  "fileHandles": [],
  "sourceInvoiceId": null
}

API requirements

Full endpoint url, header name and API token must be sent to Mynt during integration
POST https://partner-domain.com/path/to/transaction/{id}
Endpoint should:
- return 200 OK, 201 Created or 204 No Content on successful receival
- be idempotent and be able to handle multiple identical posts where data might not have changed
- be able to handle a that a RESERVED transactions is sent after a SETTLED. In such a case the reservation can be thrown away
- accept a header for the API token, partner-api-token: xxx....secret...yyy (integrating Partner may choose a different header name)
Endpoint may:
- apply IP allow-listing in the production environment (Mynt IP addresses will be provided on demand)
- return other error codes should anything fail during message processing

Retries

Should the sending of a transaction fail for whatever reason, Mynt will retry sending the transaction several times during a period of time with increasing delay between the retries. Completely giving up only after 4 days.

Transaction Properties

Sign, amount is always relative to the account, i.e.
- purchases and other transactions where money is leaving the account has negative sign
- deposits, reversals and other transactions where money is entering the account has positive sign
The description property is suitable to display to the user.
The transaction date is in the timezone of the card terminal where the purchase was made. E.g. if you have a coffee in New York at 3 pm, that will be the transaction date. The settlement date is in the Swedish timezone.
Has 4 possible states

RESERVED - a purchase was made and that the money has been reserved on the account. Whenever a settlement or cancellation occurs the reservation looses its significance.
SETTLED - a transaction was finally concluded and money drawn from the account
CANCELLED - a previous reservation was cancelled and no money was drawn
REJECTED - indicates that a purchase attempt was made but was rejected before any money was reserved or drawn. This is not a transaction that should be accounted for and typically not to be shown to the user. However, it may be useful for support.

The diagram describes the typical state transitions for a purchase, however, exceptions to this can and will occur. A transaction might very well be sent directly in the SETTLED or CANCELLED state, skipping the RESERVED state.

Transaction behavior

There are a few things to be aware of when handling transactions:

A transaction may be SETTLED with the full amount or multiple times with partial amounts.
A CANCELLED transaction may be followed by one or multiple SETTLED transactions. This is due to behavior in the card network and cannot be controlled by Mynt.
There could be transactions not tied to a specific user or card, for example top ups, credited top ups or fees.
In the dev environment, Mynt will occasionally create random transactions on the account that are sent via the Transaction Webhook. These are not real transactions coming from the card processor, meaning that the account balance will not be affected when such transactions are created in our dev environment. This is intended for testing the reception and handling of webhook messages.
Even after a SETTLED transaction has been sent, new versions for the same transactionId can be sent later with a new rev (revision). This may happen for partial amounts or when other details change and are communicated to us as the Issuer.

Overview

Text Link