API transaction validation

From Wiki

(Difference between revisions)
Jump to: navigation, search
David Benham (Talk | contribs)
David Benham (Talk | contribs)
Line 9: Line 9:
<br>
<br>
-
== Single transaction validation ==
+
== 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.
+
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.
<br>
<br>
-
== Batch validation ==
+
== Batch Transaction 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.  
+
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.  
-
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|API authentication and authorization]].
As this endpoint is part of our overall API infrastructure, it uses the user-based OAUTH2 token explained in [[API_authentication|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.'''<br>
+
'''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.'''<br>
-
=== How to call it ===
+
=== How to Call the API ===
Line 36: Line 35:
</source>
</source>
<br>
<br>
-
'''Request body:'''<br>
+
'''Request Body:'''<br>
-
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.<br>
+
The request body contains a rangen array of transaction objects. Each, each of them transaction object representsing the action that should be executed, the transaction itself, and any additional parameters if needed.<br>
Transactions are identified either by transaction ID or by orderRef/TransactionDate/Timezone.<br>
Transactions are identified either by transaction ID or by orderRef/TransactionDate/Timezone.<br>
Line 57: Line 56:
-
===Available operations===
+
===Available Operations===
''' Approve '''
''' Approve '''
-
via transaction ID:<br>
+
Via transaction ID:<br>
<div style="overflow:auto; padding: 4px .2em; word-spacing: 4px; border: 1px dashed #2F6FAB; background:#F9F9F9">
<div style="overflow:auto; padding: 4px .2em; word-spacing: 4px; border: 1px dashed #2F6FAB; background:#F9F9F9">
<source lang="JavaScript">
<source lang="JavaScript">
Line 76: Line 75:
<br>
<br>
-
via orderRef/TransactionDate/Timezone:<br>
+
Via orderRef/TransactionDate/Timezone:<br>
<div style="overflow:auto; padding: 4px .2em; word-spacing: 4px; border: 1px dashed #2F6FAB; background:#F9F9F9">
<div style="overflow:auto; padding: 4px .2em; word-spacing: 4px; border: 1px dashed #2F6FAB; background:#F9F9F9">
<source lang="JavaScript">
<source lang="JavaScript">
Line 109: Line 108:
<br>
<br>
-
via orderRef/TransactionDate/Timezone:<br>
+
Via orderRef/TransactionDate/Timezone:<br>
<div style="overflow:auto; padding: 4px .2em; word-spacing: 4px; border: 1px dashed #2F6FAB; background:#F9F9F9">
<div style="overflow:auto; padding: 4px .2em; word-spacing: 4px; border: 1px dashed #2F6FAB; background:#F9F9F9">
<source lang="JavaScript">
<source lang="JavaScript">
Line 129: Line 128:
''' Amend '''
''' Amend '''
-
via transaction ID:<br>
+
Via transaction ID:<br>
<div style="overflow:auto; padding: 4px .2em; word-spacing: 4px; border: 1px dashed #2F6FAB; background:#F9F9F9">
<div style="overflow:auto; padding: 4px .2em; word-spacing: 4px; border: 1px dashed #2F6FAB; background:#F9F9F9">
<source lang="JavaScript">
<source lang="JavaScript">
Line 158: Line 157:
<br>
<br>
-
via orderRef/TransactionDate/Timezone:<br>
+
Via orderRef/TransactionDate/Timezone:<br>
<div style="overflow:auto; padding: 4px .2em; word-spacing: 4px; border: 1px dashed #2F6FAB; background:#F9F9F9">
<div style="overflow:auto; padding: 4px .2em; word-spacing: 4px; border: 1px dashed #2F6FAB; background:#F9F9F9">
<source lang="JavaScript">
<source lang="JavaScript">
Line 189: Line 188:
'''Please note:'''<br>
'''Please note:'''<br>
-
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.<br>
+
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.<br>
<br>
<br>
-
Setting the approve parameter to true will first amend the transaction and then approve it afterwards right away.
+
Setting the approve parameter to "true" will first amend the transaction and then approve it immediately afterward.
<br>
<br>
-
=== Request body ===
+
=== Request Body ===
Line 243: Line 242:
-
The needed data (transaction ID etc.) can be pulled via the GET method of this endpoint, please see [[API_get_transactions_list|GET transactions (list)]] for details.<br>
+
The required data (transaction ID etc.) can be pulled via the GET method of this endpoint, please see [[API_get_transactions_list|GET transactions (list)]] for details.<br>
Line 249: Line 248:
<br>
<br>
-
=== Response body ===
+
=== Response Body ===
<div style="overflow:auto; padding: 4px .2em; word-spacing: 4px; border: 1px dashed #2F6FAB; background:#F9F9F9">
<div style="overflow:auto; padding: 4px .2em; word-spacing: 4px; border: 1px dashed #2F6FAB; background:#F9F9F9">
Line 258: Line 257:
</source>
</source>
</div>
</div>
-
The provided job ID will allow you to check the status of the processing job up until 60 days after the job creation.
+
The provided job ID will allow you to check the status of the processing job up for 60 days after the job was created.
<br>
<br>
-
=== Job status endpoint ===
+
=== Job Status Endpoint ===
-
==== Overall job status ====
+
==== Overall Job Status ====
'''Method:'''<br>
'''Method:'''<br>
Line 275: Line 274:
<br>
<br>
-
''' Response body '''
+
''' Response Body '''
<div style="overflow:auto; padding: 4px .2em; word-spacing: 4px; border: 1px dashed #2F6FAB; background:#F9F9F9">
<div style="overflow:auto; padding: 4px .2em; word-spacing: 4px; border: 1px dashed #2F6FAB; background:#F9F9F9">
Line 291: Line 290:
</source>
</source>
</div>
</div>
-
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.
+
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 ====
+
==== 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.
+
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:'''<br>
'''Method:'''<br>
Line 310: Line 309:
<br>
<br>
-
''' Response body '''
+
''' Response Body '''
<div style="overflow:auto; padding: 4px .2em; word-spacing: 4px; border: 1px dashed #2F6FAB; background:#F9F9F9">
<div style="overflow:auto; padding: 4px .2em; word-spacing: 4px; border: 1px dashed #2F6FAB; background:#F9F9F9">
Line 358: Line 357:
https://api.awin.com/advertisers/<yourAdvertiserId>/transactions/jobs
https://api.awin.com/advertisers/<yourAdvertiserId>/transactions/jobs
</source>
</source>
-
<br>
 
-
 
-
<br>
 
-
 
-
== 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.
 
-
 
-
<br>
 
-
<br>
 
-
<br>
 
-
<br>
 
-
<br>
 
-
<br>
 
-
<br>
 
<br>
<br>

Revision as of 11:53, 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.


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 a rangen array of transaction objects. Each, each of them transaction object representsing 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