This guide outlines the backend changes required to support transactions API v2.

Transactions API v2

To support Mobile SDK 4, your backend must migrate to version 2 of our transactions API. We tried to make migration as painless as possible. Most concepts remain unchanged, but the following architectural changes are important:

A v2 transaction is the main payment object. It consists of zero or more sub-transactions, called attempts.
A transaction can currently have up to 10 failed payment attempts and at most one successful payment attempt.
Refunds are modeled as credit attempts in the same transaction
It is no longer necessary to create separate init requests for web and Mobile SDK transactions
v2 transaction IDs are longer than v1 IDs, as they are now UUID-based

Note: Currently, our payment page does not support retries. Web transactions therefore do not contain more than one payment attempt.

Endpoints

Endpoints have moved to their v2 equivalent with init and transaction operations remaining the same.

/v1/transactions → /v2/transactions
/v1/transactions/{transactionId}/<operation> → /v2/transactions/{transactionId}/<operation>

A new endpoint has been added for attempt details. See section below.

init

The v2 init request follows the same structure as the v1 request.

The most noteworthy changes are:

returnMobileToken no longer exists, see section below
autoSettle has been moved to option
billing.country and shipping.country now use two-letter country codes (ISO 3166-1 alpha-2)

Status / Webhook

At the root level, new fields authorizedAmount, settledAmount and refundedAmount have been added, providing an overview of the transaction's total amounts.

For example, if amount 1000 was authorized, of which 800 was settled, followed by two refunds of 100 each, the status object would contain the following values:

    "authorizedAmount": 1000,
    "settledAmount": 800,
    "refundedAmount": 200,   // 100 + 100

The webhook and status response no longer contain the details and history arrays. Instead, a new attempts array has been added with information about each attempt:

	     "attempts" : [ {
	       "attemptId" : "260506160600177319",
	       "type" : "payment",
	       "amount" : 500,
	       "acquirerAuthorizationCode" : "160600",
	       "status" : "authorized",
	       "paymentMethod" : "VIS"
	     }, {
	       "attemptId" : "260506160541937225",
	       "type" : "payment",
	       "amount" : 500,
	       "status" : "failed",
	       "paymentMethod" : "VIS"
	     }, {
	       "attemptId" : "260506160521857116",
	       "type" : "payment",
	       "amount" : 500,
	       "status" : "canceled",
	       "paymentMethod" : "PAP"
	     } ]

In this example a user first selected PayPal but canceled the process. The user then tried their Visa card but was unsuccessful. They tried with their Visa card again and succeeded this time.

Attempt detail

If needed, detailed information about each attempt can be requested from the following endpoint:

GET /v2/transactions/{transactionId}/attempts/{attemptId}

Refunds

The v2 credit request no longer creates a new transaction. Instead, a credit attempt is added to the given transaction. The attemptId is returned for reference.

Using the transaction status call, you can obtain:

the total refunded amount:

"refundedAmount" : 20

refund attempts in the list of attempts (type = credit):

  {
    "attemptId" : "260506161350969555",
    "type" : "credit",
    "amount" : 20,
    "acquirerAuthorizationCode" : "161350",
    "settledAmount" : 20,
    "status" : "settled",
    "paymentMethod" : "VIS"
  }, {
    "attemptId" : "260506160600177319",
    "type" : "payment",
    "amount" : 100,
    "acquirerAuthorizationCode" : "160600",
    "settledAmount" : 100,
    "status" : "settled",
    "paymentMethod" : "VIS"
  }

mobileToken → transactionId

mobileToken has been replaced by transactionId.

Instead of initializing a transaction with returnMobileToken=true, your backend must now send a standard /v2/transactions init request and return the transactionId to your app

API reference

The complete API reference is available here:

→ Transactions API v2

Backwards compatibility

During migration, your system will likely contain a mix of v1 and v2 transactions. To simplify integration, our v2 endpoints also accept v1 transaction IDs, allowing you to use a single v2 client implementation during the transition.

For example:

GET /v2/transactions/{v1_transactionId}

returns a v2-style status response, mapping v1 transaction details to equivalent v2 fields, including virtual attempts.

Likewise:

POST /v2/transactions/{v1_transactionId}/credit

refunds the v1 transaction through the v2 API.