API transaction validation

From Wiki

(Difference between revisions)
Jump to: navigation, search
Florian Geldner (Talk | contribs)
(Created page with '= Transaction validation API endpoints = The Awin advertiser API now supports transaction validation. As this feature is still being rolled out at the moment you might not be a...')
David Benham (Talk | contribs)
Line 1: Line 1:
-
= Transaction validation API endpoints =  
+
= 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.
-
The Awin advertiser API now supports transaction validation. As this feature is still being rolled out at the moment you might not be able to use it yet. Please contact support or your dedicated contact for further questions around the availability.
 

Revision as of 11:43, 17 July 2019

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.


Batch validation

Advertisers can use our batch validation endpoint to validate (approve, decline, amend) batches of transactions. A JSON-formated list of transactions can be transferred all at once, which will then be processed asynchronously. To monitor the progress we provide a job ID that can be queried using a dedicated endpoint.

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

Please make sure to send your request in a timely manner to ensure it can be processed in time. To be taken into account for invoicing during the nights following the 15th of the month and the last day of the month we advise to send the request not later than 12 hours before midnight CET.


How to call it

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 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 afterwards right away.



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 needed 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 until 60 days after the job creation.


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 lists 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



Single transaction validation

For cases where the realtime 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 if your use case matches the functionality of the endpoint. Advertisers who process multiple transactions at once should use our batch validation endpoint instead.









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