API transaction validation

From Wiki

Jump to: navigation, search

Contents

Transaction Validation API Endpoint

The Awin advertiser API supports transaction validations, which enables you to approve, decline, and amend transactions with the Awin API.

The Transaction Validation API features a batch endpoint, which allows you 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.

Awin aims to process your transaction validation requests within your company’s financial time restrictions. Accordingly, we advise that you submit requests by 12:00PM CET on the 15th day of the month, and by 12:00PM CET on the last day of the month.

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.



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 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 with transactionId:

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


Approve with orderRef, transactionDate, and timezone:

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


Decline

Decline with transactionId:

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


Decline with orderRef, transactionDate, and timezone:

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



Amend

Amend with 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 with 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. Below is an example of a batch of three transactions; 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) for details.



Response Body

{
 "jobId": "5cbefc8646e0fb0001c4670e"
}

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


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:

Response Code Response Message Possible Response Reason
200 OK The transaction was validated as desired.
304 NOT_MODIFIED The transaction was already in the desired commission state. For example, trying to decline a declined transaction.
404 NOT_FOUND The transactionId or (orderRef, transactionDate, timezone) did not correspond to a transaction.
422 UNPROCESSABLE_ENTITY Unable to complete the request due to the current transaction state. For example, trying to approve a declined transaction.

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