API Documentation

Introduction

AfterPay offers a full WSI compliant web service. This document describes the most important operations of the API.

Technical requirements

AfterPay uses XML requests and responses for operation.

In order to use the AfterPay webservices, you need:

  • SOAP v1.1 protocol stack
  • HTTPS support (HTTP not supported)

Payment Methods

Currently, AfterPay supports these payment methods:

Method Description
B2C invoice NL AfterPay for Dutch consumers
B2C invoice BE AfterPay for Belgium consumers
B2B invoice NL AfterPay for Dutch companies
B2C direct debit NL AfterPay for Dutch consumers (Direct Debit)

Required fields per method

Below are the most important fields listed per payment method, for a complete list of all objects in the authorization, please check this overview.

Required fields B2C invoice NL

Billing

Personal

  • Initial(s)
  • Last name (including prefixes)
  • Gender
  • Date of birth
  • Telephone number (fixed or mobile)
  • E-mail address

Address

  • Streetname
  • Housenumber (separate)
  • Housenumber addition (preferably separate, otherwise include in housenumber)
  • Postal code
  • City
  • Country

Shipping

Personal
Note: Only if different from billing address. If not, then re-use billing information.

  • Initial(s)
  • Last name (including prefixes)
  • Gender
  • Date of birth
  • Telephone number (fixed or mobile)
  • E-mail address

Address
Note: Only if different from billing address. If not, then re-use billing information.

  • Streetname
  • Housenumber (separate)
  • Housenumber addition (preferably separate, otherwise include in housenumber)
  • Postal code
  • City
  • Country

Required fields B2C invoice BE

Billing

Personal

  • Initial(s)
  • Last name (including prefixes)
  • Gender
  • Date of birth
  • Telephone number (fixed or mobile)
  • E-mail address

Address

  • Streetname
  • Housenumber (separate)
  • Housenumber addition (preferably separate, otherwise include int housenumber)
  • Postal code
  • City
  • Country

Shipping

Personal
Note: Only if different from billing address. If not, then re-use billing information.

  • Initial(s)
  • Last name (including prefixes)
  • Gender
  • Date of birth
  • Telephone number (fixed or mobile)
  • E-mail address

Address
Note: Only if different from billing address. If not, then re-use billing information.

  • Streetname
  • Housenumber (separate)
  • Housenumber addition (preferably separate, otherwise include in housenumber)
  • Postal code
  • City
  • Country

Required fields B2B invoice NL

Billing

Company info

  • Company name
  • COC number
  • Initial(s)
  • Last name (including prefixes)
  • Telephone number (fixed or mobile)
  • E-mail address

Address

  • Streetname
  • Housenumber (separate)
  • Housenumber addition (preferably separate, otherwise include int housenumber)
  • Postal code
  • City
  • Country

Shipping

Address
Note: Only if different from billing address. If not, then re-use billing information.

  • Streetname
  • Housenumber (separate)
  • Housenumber addition (preferably separate, otherwise include in housenumber)
  • Postal code
  • City
  • Country

Note: different company info for shipping is not supported.

Required fields B2C direct debit NL

Billing

Personal

  • Initial(s)
  • Last name (including prefixes)
  • Gender
  • Date of birth
  • Telephone number (fixed or mobile)
  • E-mail address
  • Bankaccount number (IBAN)

Address

  • Streetname
  • Housenumber (separate)
  • Housenumber addition (preferably separate, otherwise include int housenumber)
  • Postal code
  • City
  • Country

Shipping

Personal
Note: Only if different from billing address. If not, then re-use billing information.

  • Initial(s)
  • Last name (including prefixes)
  • Gender
  • Date of birth
  • Telephone number (fixed or mobile)
  • E-mail address

Address
Note: Only if different from billing address. If not, then re-use billing information.

  • Streetname
  • Housenumber (separate)
  • Housenumber addition (preferably separate, otherwise include in housenumber)
  • Postal code
  • City
  • Country

Webservice locations

Authorization

The authorization operation is used to send an order to the authorization webservice. The webservice will validate the request and send a response.

Authorization proces

ap-flow

 

 

Example request

 

Below you will find an example authorization request for each payment method.

Need more technical info?
Please check this attachment, for a complete overview of all objects and fields.

 

Example request B2C invoice NL

Below is an authorization request, containing:

  • 1 product
  • Shipping costs
  • AfterPay service fee
  • Discount
  • Alternate shipping address
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <ns1:validateAndCheckB2COrder xmlns:ns1="http://www.afterpay.nl/ad3/">
      <authorization>
        <merchantId>2016109910?</merchantId>
        <password>hdye648fhd8</password>
        <portfolioId>1</portfolioId>
      </authorization>
      <b2corder>
        <bankaccountNumber/>
        <currency>EUR</currency>
        <ipAddress>123.321.123.321</ipAddress>
        <orderlines>
          <articleDescription>Product 1</articleDescription>
          <articleId>0077924028694</articleId>
          <quantity>1</quantity>
          <unitprice>9990</unitprice>
          <vatcategory>1</vatcategory>
        </orderlines>
        <orderlines>
          <articleDescription>Shipping costs</articleDescription>
          <articleId>SHIP</articleId>
          <quantity>1</quantity>
          <unitprice>399</unitprice>
          <vatcategory>1</vatcategory>
        </orderlines>
        <orderlines>
          <articleDescription>AfterPay payment costs</articleDescription>
          <articleId>FEE</articleId>
          <quantity>1</quantity>
          <unitprice>95</unitprice>
          <vatcategory>1</vatcategory>
        </orderlines>
        <orderlines>
          <articleDescription>Discount</articleDescription>
          <articleId>DISC</articleId>
          <quantity>1</quantity>
          <unitprice>-500</unitprice>
          <vatcategory>1</vatcategory>
        </orderlines>
        <ordernumber>123456</ordernumber>
        <parentTransactionreference/>
        <shopper/>
        <totalOrderAmount>9984</totalOrderAmount>
        <b2cbilltoAddress>
          <city>Heerenveen</city>
          <housenumber>90</housenumber>
          <housenumberAddition>B</housenumberAddition>
          <isoCountryCode>NL</isoCountryCode>
          <postalcode>8441ER</postalcode>
          <streetname>KR Poststraat</streetname>
          <referencePerson>
            <dateofbirth>1980-12-12T00:00:00</dateofbirth>
            <emailaddress>test@afterpay.nl</emailaddress>
            <gender>M</gender>
            <initials>J</initials>
            <isoLanguage>NL</isoLanguage>
            <lastname>Doe</lastname>
            <phonenumber1>0031513744112</phonenumber1>
          </referencePerson>
        </b2cbilltoAddress>
        <b2cshiptoAddress>
          <city>Heerenveen</city>
          <housenumber>80</housenumber>
          <housenumberAddition>A</housenumberAddition>
          <isoCountryCode>NL</isoCountryCode>
          <postalcode>8441ER</postalcode>
          <streetname>KR Poststraat</streetname>
          <referencePerson>
            <dateofbirth>1980-12-12T00:00:00</dateofbirth>
            <emailaddress>test@afterpay.nl</emailaddress>
            <gender>M</gender>
            <initials>J</initials>
            <isoLanguage>NL</isoLanguage>
            <lastname>Doe</lastname>
            <phonenumber1>0031513744112</phonenumber1>
          </referencePerson>
        </b2cshiptoAddress>
      </b2corder>
    </ns1:validateAndCheckB2COrder>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

 

Need more technical info?
Please check this attachment, for a complete overview of all objects and fields.

Example request B2C invoice BE

Below is an authorization request, containing:

  • 1 product
  • Shipping costs
  • AfterPay service fee
  • Discount
  • Alternate shipping address
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="http://www.afterpay.nl/ad3/">
  <SOAP-ENV:Body>
    <ns1:validateAndCheckB2COrder>
      <authorization>
        <merchantId>300004511</merchantId>
        <password>hdh356456yh</password>
        <portfolioId>3</portfolioId>
      </authorization>
      <b2corder>
        <bankaccountNumber/>
        <currency>EUR</currency>
        <extrafields/>
        <ipAddress>212.88.242.42</ipAddress>
        <orderlines>
          <articleDescription>Product 1</articleDescription>
          <articleId>0077924028694</articleId>
          <quantity>1</quantity>
          <unitprice>9990</unitprice>
          <vatcategory>1</vatcategory>
        </orderlines>
        <orderlines>
          <articleDescription>Shipping costs</articleDescription>
          <articleId>SHIP</articleId>
          <quantity>1</quantity>
          <unitprice>399</unitprice>
          <vatcategory>1</vatcategory>
        </orderlines>
        <orderlines>
          <articleDescription>AfterPay payment costs</articleDescription>
          <articleId>FEE</articleId>
          <quantity>1</quantity>
          <unitprice>95</unitprice>
          <vatcategory>1</vatcategory>
        </orderlines>
        <orderlines>
          <articleDescription>Discount</articleDescription>
          <articleId>DISC</articleId>
          <quantity>1</quantity>
          <unitprice>-500</unitprice>
          <vatcategory>1</vatcategory>
        </orderlines>
        <ordernumber>123456</ordernumber>
        <parentTransactionreference/>
        <shopper/>
        <totalOrderAmount>9984</totalOrderAmount>
        <b2cbilltoAddress>
                    <city>Brussel</city>
                    <housenumber>90</housenumber>
                    <isoCountryCode>BE</isoCountryCode>
                    <postalcode>1200</postalcode>
                    <streetname>Wafelstraat</streetname>
                    <referencePerson>
                        <dateofbirth>1990-01-01T00:00:00</dateofbirth>
                        <emailaddress>gert@studio100.be</emailaddress>
                        <gender>M</gender>
                        <initials>G.</initials>
                        <isoLanguage>NL</isoLanguage>
                        <lastname>Verhulst</lastname>
                        <phonenumber1>0032472067761</phonenumber1>
                    </referencePerson>
                </b2cbilltoAddress>
                <b2cshiptoAddress>
                    <city>Antwerpen</city>
                    <housenumber>1</housenumber>
                    <isoCountryCode>BE</isoCountryCode>
                    <postalcode>1000</postalcode>
                    <streetname>Moules</streetname>
                    <referencePerson>
                        <dateofbirth>1990-01-01T00:00:00</dateofbirth>
                        <emailaddress>samson@studio100.be</emailaddress>
                        <gender>M</gender>
                        <initials>S.</initials>
                        <isoLanguage>NL</isoLanguage>
                        <lastname>de Hond</lastname>
                        <phonenumber1>0032472067761</phonenumber1>
                    </referencePerson>
                </b2cshiptoAddress>
      </b2corder>
    </ns1:validateAndCheckB2COrder>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

 

Need more technical info?
Please check this attachment, for a complete overview of all objects and fields.

Example request B2B invoice NL

Below is an authorization request, containing:

  • 1 product
  • Shipping costs
  • AfterPay service fee
  • Alternate shipping address
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <ns1:validateAndCheckB2BOrder xmlns:ns1="http://www.afterpay.nl/ad3/">
      <authorization>
        <merchantId>300005753</merchantId>
        <password>a41dccb8a3</password>
        <portfolioId>5</portfolioId>
      </authorization>
      <b2border>
        <bankaccountNumber/>
        <currency>EUR</currency>
        <ipAddress>188.200.64.81</ipAddress>
        <orderlines>
          <articleDescription>Harde schijf kabel 821-0814-A voor de Apple M</articleDescription>
          <articleId>A000268</articleId>
          <quantity>1</quantity>
          <unitprice>3595</unitprice>
          <vatcategory>1</vatcategory>
        </orderlines>
        <orderlines>
          <articleDescription>Shipping</articleDescription>
          <articleId>SHIP</articleId>
          <quantity>1</quantity>
          <unitprice>695</unitprice>
          <vatcategory>1</vatcategory>
        </orderlines>
        <orderlines>
          <articleDescription>Payment fee</articleDescription>
          <articleId>FEE</articleId>
          <quantity>1</quantity>
          <unitprice>108</unitprice>
          <vatcategory>1</vatcategory>
        </orderlines>
        <ordernumber>201gg63321</ordernumber>
        <parentTransactionreference/>
        <shopper/>
        <totalOrderAmount>4398</totalOrderAmount>
        <b2bbilltoAddress>
          <city>Oirlo</city>
          <housenumber>5</housenumber>
          <housenumberAddition>A</housenumberAddition>
          <isoCountryCode>NL</isoCountryCode>
          <postalcode>5808BS</postalcode>
          <streetname>De Leng</streetname>
        </b2bbilltoAddress>
        <b2bshiptoAddress>
          <city>'s-Hertogenbosch</city>
          <housenumber>19</housenumber>
          <housenumberAddition>B</housenumberAddition>
          <isoCountryCode>NL</isoCountryCode>
          <postalcode>5211ML</postalcode>
          <streetname>Hinthamerstraat</streetname>
        </b2bshiptoAddress>
        <company>
          <cocnumber>55471123</cocnumber>
          <companyname>ICT Services BV</companyname>
        </company>
        <person>
          <dateofbirth>1970-01-01T00:00:00+01:00</dateofbirth>
          <emailaddress>test@hotmail.com</emailaddress>
          <gender/>
          <initials>F</initials>
          <isoLanguage>NL</isoLanguage>
          <lastname>Steeghs</lastname>
          <phonenumber1>0657584428</phonenumber1>
          <phonenumber2/>
          <prefix/>
          <title/>
        </person>
      </b2border>
    </ns1:validateAndCheckB2BOrder>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

 

Notes

  • DOB not needed to be asked in checkout – send dummy value as in example
  • Gender not needed to be asked in checkout – send empty value as in example
  • Only COC number and Company name are mandatory, other company fields not needed

Need more technical info?
Please check this attachment, for a complete overview of all objects and fields.

Example request B2C direct debit NL

Below is an authorization request, containing:

  • 1 product
  • Shipping costs
  • AfterPay service fee
  • Discount
  • Alternate shipping address
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <ns1:validateAndCheckB2COrder xmlns:ns1="http://www.afterpay.nl/ad3/">
      <authorization>
        <merchantId>2016109910?</merchantId>
        <password>hdye648fhd8</password>
        <portfolioId>1</portfolioId>
      </authorization>
      <b2corder>
        <bankaccountNumber>NL91ABNA0417164300</bankaccountNumber>
        <currency>EUR</currency>
        <ipAddress>123.321.123.321</ipAddress>
        <orderlines>
          <articleDescription>Product 1</articleDescription>
          <articleId>0077924028694</articleId>
          <quantity>1</quantity>
          <unitprice>9990</unitprice>
          <vatcategory>1</vatcategory>
        </orderlines>
        <orderlines>
          <articleDescription>Shipping costs</articleDescription>
          <articleId>SHIP</articleId>
          <quantity>1</quantity>
          <unitprice>399</unitprice>
          <vatcategory>1</vatcategory>
        </orderlines>
        <orderlines>
          <articleDescription>AfterPay payment costs</articleDescription>
          <articleId>FEE</articleId>
          <quantity>1</quantity>
          <unitprice>95</unitprice>
          <vatcategory>1</vatcategory>
        </orderlines>
        <orderlines>
          <articleDescription>Discount</articleDescription>
          <articleId>DISC</articleId>
          <quantity>1</quantity>
          <unitprice>-500</unitprice>
          <vatcategory>1</vatcategory>
        </orderlines>
        <ordernumber>123456</ordernumber>
        <parentTransactionreference/>
        <shopper/>
        <totalOrderAmount>9984</totalOrderAmount>
        <b2cbilltoAddress>
          <city>Heerenveen</city>
          <housenumber>90</housenumber>
          <housenumberAddition>B</housenumberAddition>
          <isoCountryCode>NL</isoCountryCode>
          <postalcode>8441ER</postalcode>
          <streetname>KR Poststraat</streetname>
          <referencePerson>
            <dateofbirth>1980-12-12T00:00:00</dateofbirth>
            <emailaddress>test@afterpay.nl</emailaddress>
            <gender>M</gender>
            <initials>J</initials>
            <isoLanguage>NL</isoLanguage>
            <lastname>Doe</lastname>
            <phonenumber1>0031513744112</phonenumber1>
          </referencePerson>
        </b2cbilltoAddress>
        <b2cshiptoAddress>
          <city>Heerenveen</city>
          <housenumber>80</housenumber>
          <housenumberAddition>A</housenumberAddition>
          <isoCountryCode>NL</isoCountryCode>
          <postalcode>8441ER</postalcode>
          <streetname>KR Poststraat</streetname>
          <referencePerson>
            <dateofbirth>1980-12-12T00:00:00</dateofbirth>
            <emailaddress>test@afterpay.nl</emailaddress>
            <gender>M</gender>
            <initials>J</initials>
            <isoLanguage>NL</isoLanguage>
            <lastname>Doe</lastname>
            <phonenumber1>0031513744112</phonenumber1>
          </referencePerson>
        </b2cshiptoAddress>
      </b2corder>
    </ns1:validateAndCheckB2COrder>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

 

Need more technical info?
Please check this attachment, for a complete overview of all objects and fields.

Responses

The result object of the response contains one of the following results:

ResultId Type Description Action
0 Acceptance – Payment accepted
– Order is registered
– The amount is reserved (to be captured)
– Redirect to succespage
– Order can be processed and shipped
1 Exception – Technical error
– Order is not registered
– Payment failed
– Show error message
– Order cannot be processed
2 Validation – One or more fields contain invalid data
– Order is not registered
– Payment failed
– Show validation error(s)
– Provide option to correct data and submit again
– Order cannot be processed
3 Rejection – Payment rejected
– Order is registered
– Show rejection message
– Enable user to choose a different payment method
– Order cannot be processed

ResultId 0 – Accepted payment


  
    
      
        92cf5e9a70914d27de97e128d09d99da
        4d6d3ed9f91b7c1cefa1c960fc6cc466
        0
        A
        1463577623298
        1463577623957
        487922
      
    
  

Need more technical details?

For more technical details, please check the section on the result object.

ResultId 1 – Technical error

 



    
        
            
                1
                1423239373427
                1423239436378
            
        
    

Need more technical details?

For more technical details, please check the section on the result object.

ResultId 2 – Validation error


  
    
      
        
          field.billto.phonenumber1.missing
          billto.phonenumber1
          mobiel of vast nummer mist
        
        2
        1463547359666
        1463547359833
      
    
  

Need more technical details?

For more technical details, please check the section on the result object.

ResultId 3 – Rejected payment


  
    
      
        4a9737cb3e622b3151c4ddca2eafe6a4
        a276775aae1e23a0e830ac5f0404cdf9
        1
        Aanvraag komt niet in aanmerking voor AfterPay
        3
        W
        1463572902887
        1463572903486
        487902
      
    
  

Need more technical details?

For more technical details, please check the section on the result object.

Common issues

nl.afterpay.ad3.web.service.impl.exception.AccessDeniedException
You are using the wrong credentials (merchant ID/ portfolio ID / password), please verify you are using the credentials as provided by AfterPay.

field.billto.phonenumber1.missing
The phone number is missing or has an invalid value.

field.billto.postalcode.invalid
The postal code is invalid. Please make sure the postal code is the correct format, matching the ISO country code.

field.invalid
totalorderamount

The sum of the amounts of the orderlines does not match the totalOrderAmount. Usually, this is due to rounding errors.

field.ordernumber.exists
The ordernumber has already been registered (must be unique in a portfolio ID). This usually happens if you are trying to authorize the same order again, using the same ordernumber.
Please keep in mind that the ordernumber is registered with resultID 0 and resultID 3. In those cases, you need to use another, unique, ordernumber. With resultID 1 or 2, the ordernumber is not registered and can be used again. Best practice is to always use a new ordernumber with each authorization.

 

 

Order Maintenance

AfterPay provides online order management services. These services enable to perform maintenance operations on an authorized order.

The order management webservices is available on a separate location.

Full Capture

If a payment is accepted (resultID 0), the totalOrderAmount  is reserved and can be captured.
A full capture will capture the complete order, as sent during authorization.

The totalReservedAmount will be set to 0, the totalInvoicedAmount will be set equal to the totalOrderAmount.

AfterPay will send a payment request for this amount via e-mail.

Example request

Request:


  
  
    
      
        300005739
        ***
        1
      
      
        3003535763
        3003535763
        
          #400000730
        
        0
        0
      
    
  

 Response:


  
    
      
        2ead9ac788f963a2a0e9cc5e97f5c564
        0
        A
        1463579601704
        1463579602106
        29946
        0
        487936
      
    
  

Need more technical info?
Please check this attachment, for a complete overview of all objects and fields.

Common issues

If an error occurs, the webservice will send a response with a specific failure and the relevant field name. Below is an overview of the most common errors, with an explanation.

Order does not exist

order.notexists

The order you are trying to capture does not exist (in this merchantID/ PortfolioID combination).

Invoicenumber already exists

invoicenumber.alreadyexists

An order has already been captured, using this invoicenumber. An invoicenumber has to be unique within the merchant/porfolio combination.

Invoicenumber invalid

field.invoicenumber.invalid

The most common cause for this error is to many characters in the field. The max is 20 characters. Also, valid characters are [A-Za-z0-9_-].

Order not active

order.notactive

The order is registered, but payment was rejected (resultID 3) or the order was cancelled or removed through the AfterPay order management system. The order is not active and cannot be captured.

Partial capture

If a payment is accepted (resultID 0), the totalOrderAmount  is reserved and can be captured.
A partial capture will capture a part of the reserved amount, which will be invoiced.
The captured amount will be deducted from the totalReservedAmount.

With a partial capture, invoice lines are needed, to specify what needs te be captured. These invoice line(s) will be visible in the payment request AfterPay sends via e-mail.

For each capture, a separate invoice is created. An order can therefore have multiple invoices, for which separate payment requests will be send.

If there is a reserved amount that will never be captured (invoiced), please use the void operation to clear the remaining amount.

Example request

Request:


  
  
    
      
        300005767
        ***
        1
      
      
        
          Article description
          1
          1
          33
          3
        
        9114903541738350
        
          9114903541738350
          80202848865975488833255460755058
        
        0
        
      
    
  

Response:


  
    
      
        8d6cbd4bfa080766be81d1dc555e2795
        0
        A
        1453756686627
        33
        67
        464244
      
    
  

Need more technical info?
Please check this attachment, for a complete overview of all objects and fields.

Common issues

If an error occurs, the webservice will send a response with a specific failure and the relevant field name.

In addition to the common errors with full capture, the below errors frequently occur.

Invoicenumber amount limit

invoicenumber.amount.limit

This error occurs if the amount specified to be captured > the totalReservedAmount. It is not possible to capture more than the initially reserved amount at moment of authorization. The sum of all captures must be equal or less than this amount.

Full Refund

A full refund can be used to refund a complete invoice. The total sum of captured invoice lines will be refunded. You can use the refund operation after a capture or partial capture.

Please take note that an order can have multiple invoices, a full refund only refunds one specific invoice. If you need to refund the complete order, you will need to refund each invoice separately.

Example request

Request:


  
  
    
      
        300005767
        ***
        1
      
      
        1463613715364
        
          1463613711286
        
        1463613715364
      
    
  

Response:


  
    
      
        63e83a09fe61452fd2ea8f6032630410
        0
        A
        1463613708047
        1463613708389
        0
        0
        488004
      
    
  

Need more technical info?
Please check this attachment, for a complete overview of all objects and fields.

Common issues

Besides errors like order does not exist and order not active, below errors are frequently seen with full refund.

Invoicenumber amount limit

invoicenumber:invoicenumber.amount.limit

When using full refund, this error usually occurs when you are trying to refund an invoice that has already been refunded.

Partial Refund

A partial refund will refund a part of an invoice. The refunded amount will be deducted from the totalInvoicedAmount.

With a partial refund, invoice lines are needed, to specify what needs te be refunded. It is not required to refund existing invoice lines. It is not possible to refund more than the total order amount.

You can use the partial refund operation after a capture or partial capture.

Example request

Request:


  
  
    
      
        300005739
        ***
        1
      
      
        
          Zinzi Charms rek-armband one-s
          1
          1
          -1436
          3
        
        3003535392
        3003535392
        
          #400000729
        
        
      
    
  

 Response:


  
    
      
        9bdb7bbcfcd2accec103718d65a21799
        0
        A
        1463579176035
        1463579176420
        23470
        0
        487933
      
    
  

 

Common issues

If an error occurs, the webservice will send a response with a specific failure and the relevant field name.
The below errors frequently occur.

Invoicenumber amount limit

invoicenumber:invoicenumber.amount.limit

This error occurs if the amount specified to be refunded > the (remaining) totalInvoicedAmount. It is not possible to refund more than the initially captured amount.

Invoicenumber amount positive

invoicenumber.amount.positive

This error occurs if the total(sum) amount of all invoice lines is positive. The sum has to be negative.

Cancel

The cancel order operation can be used to cancel an authorization and can only be used if no capture has been done.
The totalReservedAmount will be set to 0., order status will be set to cancelled (statusCode V).

Example request

Request:


  
  
    
      
        300005767
        ***
        1
      
      
        
          1699838047800370
          38259013100225508837408088898064
        
      
    
  

Response:


  
    
      
        d0d3b8a3f13c8a1eed36933ddd15f5a4
        0
        V
        1463613753848
        1463613754114
        0
        0
        488036
      
    
  

 

Void

The void operation can be used to clear the remainder of the reserved amount. Any remainder that isn’t to be captured should be cleared. This is necessary to avoid that these amounts are taken into account in any subsequent authorization request.

The void operation is possible before and after a capture request.

Before will set the (complete) reserved amount to 0. After capture(s), it will only clear the remaining amount.

However, in case an entire order isn’t to be captured we advise you to use cancel  instead as this will update the order status to cancelled.

Example request

Request:


  
  
    
      
        300005767
        ***
        1
      
      
        
          1947894904960579
          43188150104798181430421052723879
        
      
    
  

Response:


  
    
      
        bd4b06a8cd30af0825881926828f133c
        0
        A
        1463613759308
        1463613759500
        0
        0
        488040
      
    
  

 

Other useful operations

Request Order Status

Request Order Status can be used to check if an order exists, and if so, retrieve the status and reserved and invoiced amounts.

Example request

Request:


  
  
    
      
        300005767
        ***
        1
      
      
        
          1947894904960579
          43188150104798181430421052723879
        
      
    
  

Response:


  
    
      
        9127efb5d8bfa158b6f8a6171f84570f
        0
        A
        1463613758727
        1463613758910
        0
        100
        488039
      
    
  

 

Use-cases

In this section, we will provide real-world use-cases, and how to process them using the webservice operations.

No delivery

An order is placed, but the shopper decides to cancel the complete order before anything is shipped. No capture has been done yet, so you can use cancel to remove the complete order and set the reserved amount to 0. The shopper will never receive a payment request from AfterPay.

Full delivery

An order is placed and this complete order is delivered. After delivery, you can use full capture to capture and invoice the complete order. Please note that a shopper should not receive request for payment before the goods are delivered. Therefore, it is advised to time the capture accordingly (usually after shipping the order).

Full delivery, full return

An order is placed, delivered and completely captured using a full capture. The shopper decides to return the complete order. Then you can use full refund to refund the complete amount. If a shopper has paid, then the complete amount will be refunded. If the shopper has not yet paid, then a notification will be send stating that nothing has to be paid anymore.

Full delivery, full return (in parts)

An order is placed, delivered and completely captured using a full capture. The shopper decides to return part of the order. Then decides to return the remaining part of the order as well. The complete has been returned, but in parts.

Then you can use a partial refund for each return.

 

Full delivery, partial return

An order is placed, delivered and completely captured using a full capture. The shopper decides to return part of the order. Then you can use a partial refund for that return. The shopper only needs to pay de the remaining part of the invoiced amount.

 

Partial delivery

An order is placed, but 1 product will have a delayed delivery.

First, you can use a partial capture, to invoice the product that will be delivered in time. Then, after the delayed product is shipped, you can use another partial capture, to invoice that product separately.

 

Partial delivery (incomplete)

An order is placed, but 1 product cannot be delivered.

First, you can use a partial capture, to invoice the products that will be delivered.
Then, to clear the remaining reserved amount, you can use void.

 

Partial cancel, partial delivery

An order is placed for multiple products, but the shopper cancels 1 product.

There is no such thing as a partial cancel, so you need to do a partial capture, for the products that will be shipped. Then do a void for the cancelled product.

Note: you must first do capture, then void. If you do a void first, then you will clear the complete reserved amount. This would mean you cannot capture (invoice) the other products, that will be delivered.

 

Attachments

Authorization objects

 Authorization

Name Description
AfterPayOrder Order Object
AfterPayB2Corder B2C order details, extends an AfterPayOrder
AfterPayB2Border B2B order details, extends an AfterPayOrder
B2CAddress Address object B2C, used in AfterPayB2Corder
ReferencePerson Reference person, used in B2CAddress
Orderlines Order line array, used in AfterPayOrder
ExtraFields Can contain additional values, used in AfterPayOrder
Shopdetails Shop details, used in AfterPayOrder
Shopper Consumer details, used in AfterPayOrder
B2BAddress Address object B2B, used in AfterPayB2Border
Company Company details used in AfterPayOrder
Person Person details, used in AfterPayOrder

AfterPayOrder

Field name Data type Description Mandatory Validation
Ordernumber String Order ID of the webshop. Must be unique per portfolio YES Unique per ‘Portfolio’.
Max. 36 characters, min. 2 characters. Only A-Z,a-z 0-9 and _- are allowed. For Germany max 20 chars long.
parentTransactionreference String Transaction reference of the PSP/Intermediate party. Can be used as a key for future changes on the order. NO Min 3 chars. Max 25 chars. A-Z,a-z 0-9Transaction reference (of the Payment Servive Provider)

Should be unique in portfolio.

bankID String ID of the bank NO ID or name of the bank (NOT USED YET)
Bankaccountnumber String NO (only mandatory for direct debit) Numbers are allowed. May contain 9 or 10 digits. Are validated on format (Dutch 11-proef of banks)
currency String ISO 4217 Currency Codes YES Currently available

  • EUR
exchangeDate Date Date of exchange rate NO
exchangeRate Double Exchange rate at given exchangeDate NO F.e. 1 CHF = 0,91383 EUROMust be formatted as: 0,91333
ipAddress String IP Address of consumer YES valid ipv4 or ipv6 address
totalOrderAmount Integer Total order amount including vat YES Amount in euro cents
totalOrderNetAmount Double Amount excluding vat. Only use when billing should be done excluding vat. Only use in collaboration with AfterPay business solutions NO Amount in euro cents with 2 decimals. Example 10010,20 for: 100,1020)
orderlines OrderLine{} Orderline array YES If a webshop has no order lines deliver 1 standard order line with the description “Uw bestelling bij: (followed by the webshop name)”
extrafields ExtraFields{} Extra fields for additional data NO
Shopdetails Shopdetails Shop details object NO
shopper Shopper Shopper object NO

B2Corder

Field name Data type Description
b2cbilltoAddress B2CAddress b2cbilltoadress extends the standard address object
b2cshiptoAddress B2CAddress b2cshiptoadress extends the standard address object

B2Border

Field name Datatype Description
b2bbilltoAddress B2BAddress b2bbilltoadress extends the standard address object
b2bshiptoAddress B2BAddress b2bshiptoadress extends the standard address object
company Company Object company contains company details
costcenter String (Optional) contains order costcenter

B2Caddress

Field name Data type Description Mandatory Validation
city String City YES Max 150 characters
Housenumber String House number YES May include house number addition, will be separated automatically. (unless Housenumberaddition field is used)
Housenumberaddition String House number addition NO Max 6 characters
isoCountryCode String Country code ISO 3166-1 (2 letterig) YES ISO format 2 characters (NL,DE,BE)
Postalcode String Postalcode YES NL: ‘CCCCLL’
BE: ‘CCCC’
Region String Region NO
referencePerson referencePerson Consumer information YES
Streetname String Streetname YES Max 45 characters

ReferencePerson

Field name Data type Description Mandatory Validation
dateofbirth DateTime Date of birth customer YES Date time format ( 1980-12-12T00:00:00).
For B2B prefill with: (1970-01-01T00:00:00)
emailaddress String Email address YES Max 45 characters
gender String Gender B2C:YES
B2B:NO
B2C: M (Male) / V (Female)
B2B: send empty field
initials String Initials YES
isoLanguage String Consumer Language YES ISO language code.(supported at this moment: NL, DE, NL-BE, FR-BE)
lastname String Consumer Last name YES [a-z,0-9], no control characters
phonenumber1 String Consumer phone number can be mobile or landline YES Prefix allowed:( ) allowed

NL: +31/0031/31
Length without prefix 10 characters

BE: +32/0032/32
Mobile phone number length without prefix 10 characters.
Landline length without prefix 9 characters.

phonenumber2 String Consumer phone number can be mobile or landline NO Prefix allowed:( ) allowed

NL: +31/0031/31
Length without prefix 10 characters

BE: +32/0032/32
Mobile phone number length without prefix 10 characters.
Landline length without prefix 9 characters.

prefix String In to NO String max 10 characters.
title String Consumer title NO String max 20 characters.

Orderlines

Field name Data type Description Mandatory Validation
articleDescription String Description YES Numbers are allowed.Max 45 characters. Special characters like ^, ` etc are automatically filtered out.
articleID String Article number YES Max 25 characters.
netunitprice Double Price excluding vat NO Amount is in euro cents with 2 decimals. Example 10010,20 for: 100,1020) Only use this setting if AfterPay agrees with it!
quantity Integer Article Quanty YES Integer values > 0
Maximum value is 2147483647
unitprice Integer Unit price including vat YES Amount is in euro cents. No decimals allowed.
vatcategory Integer Vat category YES 1:High, 2:Low, 3:Zero, 4:None, 5:Middle

ExtraFields

Field name Data type Description Mandatory Validation
nameField String Name variable YES Name variable
valueField String Value variable YES Value variable

Shopdetails

Field name Data type Description Mandatory Validation
afterpaypluginsupplier String Name is given by AfterPay NO
afterpayPluginVersion String Plug-in versio ID NO
intermediarID Integer ID is given by AfterPay NO
shopURL String URL of the webshop NO
webshoplanguage String Programming language of the webshop NO
webshopplatform String F.e. Magento, OScommerce NO
webshopplatformversion String Webshop platform version NO

Shopper

Field name Data type Description Mandatory Validation
afterPayId String Unique AfterPay ID NO [a-z,0-9], no control characters
afterPayToken String Token NO [a-z,0-9], no control characters
customerNumber Integer Customer number NO Customer ID from webshop. Min 4 integers
finbox Boolean Does the customer use Finbox? NO Not used
hasCustcard Boolean Has customer card? NO
HasPayments Boolean Has positive payment history NO
profileCreated DateTime Date time of account creation YES Date time formaat ( 1980-12-12T00:00:00)
referString String Reference of shopper entry. Used to recognize affiliate networks NO
Fingerprint String Fingerprint on the basis of useragent + resolution For more information please contac AfterPay business solutions NO MD5 String

B2BAddress

Field name Data type Description Mandatory Validation
city String City YES Max 150 characters
Housenumber String House number YES May include house number addition, will be separated automatically. (unless Housenumberaddition field is used)
Housenumberaddition String House number addition NO Max 6 characters
isoCountryCode String Country code ISO 3166-1 (2 letterig) YES ISO format 2 characters (NL,DE,BE)
Postalcode String Postalcode YES NL: ‘CCCCLL’
BE: ‘CCCC’
Region String Region NO
Streetname String Streetname YES Max 45 characters
careof String Person that accepts the package NO [a-z,0-9], no control characters
phone String Phone number NO [a-z,0-9], no control characters

Company

Field name Data type Description Mandatory Validation
cocnumber String Chamber of commerce number YES [a-z,0-9], no control characters
companyname String Company name YES [a-z,0-9], no control characters
department String Company department NO [a-z,0-9], no control characters
establishmentnumber String Establishment number NO Always 12 digits
vatnumber String VAT number NO [a-z,0-9], max. 14 characters

Person

Field name Data type Description Mandatory Validation
dateofbirth DateTime Date of birth customer B2C:YES
B2B:NO
Date time format ( 1980-12-12T00:00:00).
For B2B prefill with: (1970-01-01T00:00:00)
emailaddress String Email address YES Max 45 characters
gender String Gender B2C:YES
B2B:NO
B2C: M (Male) / V (Female)
B2B: send empty field
initials String Initials YES
isoLanguage String Consumer Language YES ISO language code.(supported at this moment: NL, DE, NL-BE, FR-BE)
lastname String Consumer Last name YES [a-z,0-9], no control characters
phonenumber1 String Consumer phone number can be mobile or landline YES Prefix allowed:( ) allowed

NL: +31/0031/31
Length without prefix 10 characters

BE: +32/0032/32
Mobile phone number length without prefix 10 characters.
Landline length without prefix 9 characters.

phonenumber2 String Consumer phone number can be mobile or landline Prefix allowed:( ) allowed

NL: +31/0031/31
Length without prefix 10 characters

BE: +32/0032/32
Mobile phone number length without prefix 10 characters.
Landline length without prefix 9 characters.

prefix String In to NO String max 10 characters.
title String Consumer title NO String max 20 characters.

Order maintenance objects

Order Maintenance

Name Description
Authorization Webservice authorization details
TransactionKey Sub object for identification of authorization/transaction used in Order management object
Invoicelines Sub object with order details used in capture and refund object
Capture Invoice details for capture
Refund Invoice details for refund
Order Management Additional details for order maintenance

Authorization

Field name Data type Description
authorizationtoken String Not used
securityhash String Not used
merchantId Integer Must match the ‘Business Partner ID’ provided by AfterPay (also called relation number).
PortefeuilleId Integer Must match the ‘Portefeuille’, provided by AfterPay
Password String Must match the ‘Password’ provided by AfterPay

Transactionkey

Field name Data type Description
Ordernumber String The merchant’s order number
parentTransactionreference String Transaction reference used by PSP/Merchant for authorization. (Field: parentTransactionreference)

Invoicelines

Field name Data Type Description Required Validation
articleDescription String Description of the article / item. YES Numbers are allowed.Maximum of  45 characters. Punctuations will be filtered from the description.
articleID String The SKU of the Business Partner YES Maximum 25 characters.
netunitprice Double Unitprice excluding VAT. Only submitted when the shop only uses prices excluding VAT.. Only use with consultation of AfterPay NO Amount is in eurocents with 2 decimals. Example 10010,20 (normal notation € 100,1020)
quantity Integer Quantity of the ordered items YES Integer value > 0
Maximum value 2147483647
unitprice Integer Unitprice including VAT YES Amount is in eurocents
vatcategory Integer VAT category YES 1:high category, 2:low category, 3:nul category, 4:no category, 5:middle category.

Capture

Field name Data Type Required Description
Extrafields Array of extrafields NO
Invoicelines Array of invoicelines NO with full capture
/
YES with partial capture
Invoice lines. Only required to submit with a partial capture. This field is not used with full captures.
invoicenumber String YES Invoicenumber. For Germany counts a limit length of 7 characters Validation [A-Za-z0-9_-]. For Netherlands counts a limit length of 20 characters.
Transactionreference String NO
/
YES for collecting PSP
Transaction reference. (Optional) (Max 25 characters, will be truncated if longer) (Mandatory for collecting PSP)
Capturedelaydays Integer NO Amount of days delay before sending the invoice. Not operational.
Shippingcompany String NO Name of the shipping company
Trackingnumber String NO Tracktrace number of the shipping
Transactionkey TransactionKey YES Reference to the original authorisation (order)

Refund

Field name Data Type Required Description
Extrafields Array of extra fields NO
Invoicelines Array of invoice lines NO with full capture
/
YES with partial capture
Refund rules. Only required with partial refunds. A refund rule always contains a negative amount.
invoicenumber String YES Invoice number. For Germany counts a limit length of 7 characters Validation [A-Za-z0-9_-]. For Netherlands counts a limit length of 20 characters.
Transactionreference String NO
/
YES for collecting PSP
Transaction reference. (Optional) (Max 25 characters, will be truncated if longer) (Mandatory for collecting PSP)
creditInvoicenNumber String NO Credit invoice number. (Optional)
Transactionkey Transaction Key YES Reference to original authorization (order)

Ordermanagement

Field name Data Type Required Description
Extrafields Array of extra fields NO
Invoicelines Array of invoice lines NO Not used
invoicenumber String NO Not used
Transactionreference String NO
/
YES for collecting PSP
Transaction reference. (Optional) (Max 25 characters, will be truncated if longer) (Mandatory for collecting PSP)
Transactionkey Transaction Key YES Reference to original authorization (order)

Result object

Field name: Data Type: Description:
AfterPayOrderReference String Unique ID for the order
transactionID Int Unique ID for the transaction
resultID Int Result ID result of the SOAP request:
0: Accepted by AfterPay provided that it is in combination with statusCode = A
1: Exeption in the request/response
2: Validation errors in the request
3: Rejected (payment refused) by AfterPay
4: Pending
statuscode String Status of the order: A:accepted, W:refused, P:pending
checksum String Checksum on several fields that are delivered by the webshop
De checksum is a MD5 on:
– MerchantID
– totalOrderAmount
– ResultID
– TransactieID
– Ordernummer merchantThe fields will be connected with ‘-‘
Example:
100010-3570-0-726000-B2b8270
extrafields ExtraFields[] Array with optional extra fields
failures FieldValidationFailuresExt[] List with validation errors (if applicable)
rejectCode String Rejection code reason
rejectDescription String Description of the rejection code
Substatuscode String Only used in combination with status Pending
Timestampin Int Unix timestamp of the entry of order in milli-seconds
Timestampout Int Unix timestamp of the processing of the order in milli-seconds

FieldValidationFailureExt

Field name: Data Type: Description:
fieldname String Field name with the wrong value
failure String Description of the failure
suggestedvalue String Suggested value

Rejectcode and description

rejectCode: rejectDescription:
1 Order is not accepted by AfterPay
29 Amount of first AfterPay order is to high
30 Maximum open orders reached
36 Invalid e-mail address
40 Age is under 18
42 Incorrect address
47 Order amount to low
71 Invalid company details and/or coc number

BPC

BPC | de Business Partner Console het Order Management systeem voor je AfterPay bestellingen.


De Business Partner Console is de plek waar je alle AfterPay orders terug kunt vinden die via je webshop bij ons zijn binnengekomen. Je hebt hiervoor een registratie e-mail ontvangen bij aanvang van de implementatie.

Je kunt hier ook je AfterPay bestellingen beheren en de uitbetaal-specificaties inzien. Op deze pagina kun je de meest gebruikte functies van de Business Partner Console terug vinden.

Controleer dus snel of je toegang werkt en of je overal bij kan!

Wil je meteen naar de login pagina? Klik dan op onderstaande knop.


Suggest Edit