Deutsch | English | Español | Français | Italiano | Nederlands | Polski | Português (Brasil) | Svenska

Transaction Validation API Endpoint

The Transaction Validations API allows you to approve, decline, and amend transactions with the Awin API. You can also use the Transaction Validation API to group multiple validation requests into a single submission.

The transaction validation API endpoint is part of Awin’s overall API infrastructure. As such, the endpoint utilises a user-based OAUTH2 token. For more information about OAUTH2, refer to the API Authentication and Authorisation Wiki page.

Batch Transaction Validation

Batch transaction validation enables the transfer and subsequent processing of a list of one or more JSON-formatted transactions at once. To allow you to monitor the progress of your validation requests, Awin provides a trackable jobID.

Calling the API

Method:
POST

content-type:
application/json

URL:

https://api.awin.com/advertisers/<yourAdvertiserId>/transactions/batch

Request Body:
The request body contains an array of transaction objects. Each object represents the action to be executed, the transaction, and if required, any additional parameters. Transactions are identified either by transactionId, or by orderRef, transactionDate, and timezone.

"transactionId": "484816099",

"orderRef": "123ABC555",
"transactionDate": "2017-02-20T22:04:00",
"timezone": "Europe/Paris"

Available Operations

Approve

Approve by transactionId:

{
  "action": "approve",
  "transaction": {
    "transactionId": 1234567
  }
}

Approve by orderRef, transactionDate, and timezone:

{
  "action": "approve",
  "transaction": {
    "orderRef": "123ABC555",
    "transactionDate": "2017-02-20T22:04:00",
    "timezone": "Europe/Paris"
  }
}

Decline

Decline by transactionId:

{
  "action": "decline",
  "transaction": {
    "transactionId": 1234567,
    "declineReason": "order returned"
  }
}

Decline by orderRef, transactionDate, and timezone:

{
  "action": "decline",
  "transaction": {
    "orderRef": "123ABC555",
    "transactionDate": "2017-02-20T22:04:00",
    "timezone": "Europe/Paris",
    "declineReason": "order returned"
  }
}

Amend

Amend by transactionId:

{
  "action": "amend",
  "approve": false,
  "transaction": {
    "transactionId": 1234567,
    "amendReason": "partial return",
    "currency": "EUR",
    "saleAmount": 55.96,
    "transactionParts": [
      {
        "amount": 44.76,
        "commissionGroupCode": "DEFAULT"
      },
      {
        "amount": 11.20,
        "commissionGroupCode": "EXISTING"
      }
    ]
  }
}

Amend by orderRef, transactionDate, and timezone:

{
  "action": "amend",
  "approve": false,
  "transaction": {
    "orderRef": "123ABC555",
    "transactionDate": "2017-02-20T22:04:00",
    "timezone": "Europe/Paris",
    "amendReason": "partial return",
    "currency": "EUR",
    "saleAmount": 55.96,
    "transactionParts": [
      {
        "amount": 44.76,
        "commissionGroupCode": "DEFAULT"
      },
      {
        "amount": 11.20,
        "commissionGroupCode": "EXISTING"
      }
    ]
  }
}

Note:
To ensure the integrity of amendment transactions, the sum of the transaction parts must be identical to the saleAmount. Otherwise, to balance possible differences, the "DEFAULT" commissionGroup is adjusted automatically.
If you set the approve parameter to "true", the API first amends the transaction, and then approves it immediately thereafter.

Request Body

You must combine request body actions with the final batch request body. The following example is a batch of three transactions, and includes one approve transaction, one amend transaction, and one decline transaction.

[
  {
    "action": "amend",
    "approve": false,
    "transaction": {
      "transactionId": "484816099",
      "amendReason": "partial return",
      "currency": "EUR",
      "saleAmount": 44.76,
      "transactionParts": [
        {
          "amount": 44.76,
          "commissionGroupCode": "DEFAULT"
        }
      ]
    }
  },
  {
    "action": "decline",
    "transaction": {
      "transactionId": 1234567,
      "declineReason": "order returned"
    }
  },
  {
    "action": "approve",
    "transaction": {
      "orderRef": "123ABC555",
      "transactionDate": "2017-02-20T22:04:00",
      "timezone": "Europe/Paris"
    }
  }
]

To obtain the necessary data, such as the transactionId, use the GET method for this endpoint. For more information, refer to GET transactions (list).

Response Body

{
  "jobId": "5cbefc8646e0fb0001c4670e"
}

For up for 60 days after you create the job, the jobId enables you to review the status of any jobs that are in process.

Job Status Endpoint

Overall Job Status

Method:
GET

URL:

https://api.awin.com/advertisers/<yourAdvertiserId>/transactions/jobs/<jobId>

Response Body

{
  "jobId": "5cbefc8646e0fb0001c4670e",
  "status": "DONE",
  "transactionCount": 100,
  "allTransactions": null,
  "errorCount": 0,
  "failedTransactions": null,
  "creationDate": "2017-02-20T22:04:00",
  "completionDate": "2017-02-20T22:24:00"
}

If you do not query a detailed transaction list or error list for a job, the allTransactions and failedTransactions objects default to "null". For more information, refer to the Detailed Error List section on this page.

Detailed Error List

To provide an additional list of the transactions that generated an error during validation, add the "output=errors" parameter to the URL. The API lists the individual transactions that are within the failedTransactions object. To generate a full list of all transactions inside the allTransactions object, add the "output=all" parameter to the URL instead.

Method:
GET

URL:

https://api.awin.com/advertisers/<yourAdvertiserId>/transactions/jobs/<jobId>?output=errors
 
https://api.awin.com/advertisers/<yourAdvertiserId>/transactions/jobs/<jobId>?output=all

Response Body

{
  "jobId": "5cb8290460b59a6e7ae22d0b",
  "status": "DONE",
  "transactions": 2,
  "allTransactions": null,
  "errors": 2,
  "failedTransactions": [
    {
      "transactionId": 1234567,
      "orderRef": null,
      "transactionDate": null,
      "timezone": "",
      "code": "[404 NOT_FOUND]",
      "description": null
    },
    {
      "transactionId": 1234568,
      "orderRef": null,
      "transactionDate": null,
      "timezone": "",
      "code": "[404 NOT_FOUND]",
      "description": null
    }
  ],
  "creationDate": "2019-04-18T09:49:35.558",
  "completionDate": "2019-04-18T09:49:36.513"
}

Job List

To generate a list of all your jobs from the last 60 days, call the job endpoint without providing a dedicated job ID.

Method:
GET

URL:

https://api.awin.com/advertisers/<yourAdvertiserId>/transactions/jobs

Common Response Codes

The following table contains a list of possible response reasons for common response codes that may appear when using the API: