API transaction validation

From Wiki

Jump to: navigation, search

Contents

Transaction Validation API Endpoints

The Awin advertiser API now supports transaction validations, which means you can validate transactions using our API.

You can use the Batch Transaction Validation endpoint, or the Single Transaction Validation depending which is more appropriate for you.

This feature is still being rolled out at the moment, so you might not be able to use it yet. To find out if it’s available to you, please get in touch with our support team or your Awin contact.


Single Transaction Validation

For cases where the real-time validation of individual transactions (one transaction per API call) is needed, we provide a dedicated endpoint. Please get in contact with support so that we can check whether your use case matches the functionality of the endpoint. If you plan to process multiple transactions at once, please use our batch validation endpoint instead.


Batch Transaction Validation

As an advertiser, you can use our batch validation endpoint to validate (approve, decline, amend) batches of transactions. The endpoint allows you to transfer an entire list of JSON-formatted transactions in one go, which will then all be processed simultaneously. We even provide a jobID you can use to query and monitor the progress.

As this endpoint is part of our overall API infrastructure, it uses the user-based OAUTH2 token explained in API authentication and authorization.

Please send your request in plenty of time to ensure it is processed within your time restrictions. For example, to be taken into account for invoicing, we advise that you send the request by midday CET on the 15th of the month and the last day of the month.


How to Call the API

Method:
POST

URL:

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


Request Body:
The request body contains an array of transaction objects. Each of them representing the action that should be executed, the transaction itself, and any additional parameters if needed.
Transactions are identified either by transaction ID or by orderRef/TransactionDate/Timezone.

"transactionId": "484816099",


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



Available Operations

Approve

Via transaction ID:

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


Via orderRef/TransactionDate/Timezone:

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


Decline

Via transaction ID:

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


Via orderRef/TransactionDate/Timezone:

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



Amend

Via transaction ID:

{
"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"
          }
        ]
    }
}


Via orderRef/TransactionDate/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"
          }
        ]
    }
}


Please note:
To secure the integrity of the transaction for amend cases, the sum of amounts in the transaction parts needs to be identical to the saleAmount. Otherwise the "DEFAULT" commissionGroup will be adjusted automatically to balance possible differences.

Setting the approve parameter to "true" will first amend the transaction and then approve it immediately afterward.



Request Body

These actions then need to be combined to the request body for the final batch request. Here is an example of a batch of 3 transactions, one each for approve, decline and amend:

[
  {
    "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"
      }
  }
 
]


The required data (transaction ID etc.) can be pulled via the GET method of this endpoint, please see GET transactions (list) for details.



Response Body

{
 "jobId": "5cbefc8646e0fb0001c4670e"
}

The provided job ID will allow you to check the status of the processing job up for 60 days after the job was created.


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"
}

As long as you don't query a detailed transaction/error list for the job, the objects allTransactions and failedTransactions will default to "null". See 'Detailed error list' for that use case.


Detailed Error List

By adding the "output=errors" parameter to the URL we provide an additional list of the transactions that generated an error during validation. The individual transactions are listed within the failedTransactions object. By calling "output=all" a full list of all transactions is provided, in this case inside the allTransactions object.

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

Calling the job endpoint without providing a dedicated job ID will list all of your jobs for the last 60 days.

Method:
GET

URL:

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


Privacy

Due to new European legislation regarding how websites store information about you, AWIN is updating its privacy policy. You can see the new version of our policy here. If you would like to see the information we capture on this website, please click here for further details. In order to accept cookies on this site please click the 'I ACCEPT' button