Guide REST based web services in Automatisk kortbetaling via Betalingsservice

Transcription

1 Guide REST based web services in Automatisk kortbetaling via Betalingsservice Version 3.1 Nets A/S Lautrupbjerg Ballerup DK T F

2 Contents 1. Background Purpose of the REST-services Security via Certificate Input format Types of REST-services available First time payment history First time transaction(s) status service AUTH transaction service Cancel AUTH transactions service Capture AUTH transactions service Credit transaction service List temporary customer numbers Debtors contacts service Card mandate status service Transaction status service Active mandates service Outstanding payments service Transaction history service Expiring card service Transaction credit service Incomplete payment service from the Tast-selv module

3 1. Background This document describes the informational services that are used by Automatic card payments via Betalingsservice users in order to retrieve information from different logical entities created via system. This includes information about card mandates, first time payments, recurring payments and telemarketing requests. The services also allows performing actions with first time payments, such as capturing the amount, cancellation and reversal. All these services are only accessible if user is authorized with FOCES certificate. 2. Purpose of the REST-services The web-services for automatic card payments are based on REST-services. RESTservices are a simple way to implement web-services in regard to collect data and to initiate updates. The advantages of REST-services are, that they can be called any time by adding input parameters in a specific URL and receive the output by XML. It is possible to collect status on different information about the automatic card payments. As well as to initiate a few card transactions via a REST call e.g. a credit transfer, which will be described below. REST services can be implemented in the merchants existing ERP system for the purpose of introducing the business user of a standardized overview or they can be called of technical users by doing ad hoc calls and read the results directly as XML. Find examples of the call syntax and reply format under the individual services below. 3. Security via Certificate In regard to secure and authorize the system a Functional Signature Certificate (FOCES) from Nets DanID is to be used to authorize the REST-service calls. The Functional Signature Certificate is used when two systems are communicating. It is not a check of an user and a system. Find further information her: The merchant need to do the following step for implementing Functional Signature Certificate. See specific Guide for Functional Signature Certificate for Automatic card payment on Nets.eu - click here. 3

4 4. Input format The format of the different REST based web-services are: Input parameters: Name Description Format Mandatory pbsno Creditors ID with Nets Number, 1-8 digits Yes debgrno The debtor group number that the customer Number, 1-5 digits Yes is enrolled to customerno Creditors ID for the debtor String No date Date when transaction was placed Date in DDMMYY Yes format orderno Nets ID for the transaction Number No transactionid ID for transaction in NetAxept String transactionstatus The current status of the transaction: Code RESERVED, PAID, RESCANCL, REVERSED amount The amount of first time payment String CreditorReference Data specified by creditor as a reference for String No payment statuscode The current status of the transaction: Code RESERVED, PAID, RESCANCL, REVERSED reservationdate Date when reservation was made Date in DDMMYY format cardexpirydate Month of card expiration Date in MMYY format DateFrom* Begin date of the requested period Date in DDMMYY No** format DateTo* End date of the requested period Date in DDMMYY No** format transactionstatus The current status of the transaction: Code No*** RESERVED, PAID, RESCANCL, REVERSED From Start date of the requested period when String No mandate was created To End date of the requested period when String No mandate was created debtorname Debtor name retrieved via CPR lookup Number address Debtor 1st address retrieved via CPR lookup String postalcode Debtor postal code retrieved via CPR lookup Number, 4 digits city Debitor city retrieved via CPR lookup String mandatetype The type of agreement that the debtor has signed up for (e.g. always card payments, card payments until BS and so forth) 3 letters code WBS - Card until BS OCA - Card Only mandatestatus The current status of the mandate: ACTIVE, Code CANCELLED, EXPIRED mandateregdate Date when card mandate was registered Date in DDMMYY format paymentduedate Due date when payment should be done Date in DDMMYY format originalduedate Original due date when payment should be Date in DDMMYY done format 4

5 * The requested period may be maximum 1 year. Service will respond with error if period greater than one year is entered. ** If period is not entered, then the list will contain info for all registered transactions for the particular creditor (and perhaps debtor) taken for the period 1-year before the date of query. *** If no operation type is specified, then the list will contain the transactions will all possible statuses using both dates (paid_date and reservn_cancl_date). Otherwise, only corresponding dates will be used to obtain data within required time range : paid_date for PAID and REVERSED, reservn_cancl_date for RESERVE and RESCANCL. 5

6 5. Types of REST-services available The following REST-services will be available: REST-services 1-7 when first time payment together with mandate enrolment. REST-services 8-15 when no first time payment together with mandate enrolment. REST-service 16 is an extra service used if the Tast-Selv module is used. 1. First time payment history service - Get overview of mandates with 1. time payment together with enrolment for a given period. 2. First time transaction(s) status service - Get status on a specific 1. time payment success or failed. 3. AUTH transaction service - Get overview of reserved 1. time payments (AUTH) 4. Cancel AUTH transactions service - Cancel/annul a reserved 1. time payment 5. Capture AUTH transactions service - Initiate a payment process of a reserved payment (Capture) 6. Credit transaction service - Initiate a reversal/credit transfer of a specific 1. time payment. 7. List temporary customer numbers - Get list of mandates with temporary customer numbers. 8. Debtors contacts service - Get data of customers with card mandates. 9. Card mandate status service - Get overview of card mandates for a given period. 10. Transaction status service - Get status of a specific card payment. 11. Active mandates service - Get overview of all active mandates. 12. Outstanding payments service - Get overview of pending payments. 13. Transaction history service - Get overview of card payments for a given period. 14. Expiring card service - Get overview of mandates with cards that are about to expire within the coming two months. 15. Transaction credit service - Initiate a reversal/credit transfer of a specific card payment. 16. Incomplete payment service - Used when using the Tast-selv module to get list of all incomplete and unsuccessful transactions. When testing the Rest-services are to be called via: Note: be aware that in the test URL you should use your own pbs no. In production the Rest-services are to be called via: 6

7 5.1 First time payment history Description The web service provides a list of first-time payment transactions, which took place within the specified period. Output results will be sorted with the most recent on top. Input parameters /bsexpress/rest/cardpaymentfirst/history/pbsno/debgrno/datefrom/datefrom/dateto/ DateTo/customerNo/CustomerNo/status/TransactionStatus * The requested period may be maximum 1 year. Service will respond with error if period greater than one year is entered. ** If period is not entered, then the list will contain info for all registered transactions for the particular creditor (and perhaps debtor) taken for the period 1-year before the date of query. Output parameters Client will receive one or many JSON objects [pbsno, debgrno, customerno, date, orderno, transactionid, transactionstatus] Example Requests: /bsexpress/rest/cardpaymentfirst/history/24997/95623 /bsexpress/rest/cardpaymentfirst/history/24997/95623/customerno/ cust04 /bsexpress/rest/cardpaymentfirst/history/24997/95623/datefrom/010113/dateto/ /bsexpress/rest/cardpaymentfirst/history/24997/95623/status/paid /bsexpress/rest/cardpaymentfirst/history/24997/95623/datefrom/010113/dateto/131213/cus tomerno/ cust04 /bsexpress/rest/cardpaymentfirst/history/24997/95623/datefrom/010113/dateto/131213/stat us/reserved /bsexpress/rest/cardpaymentfirst/history/24997/95623/customerno/ cust04/statu s/rescancl /bsexpress/rest/cardpaymentfirst/history/24997/95623/datefrom/010113/dateto/131213/cus tomerno/ cust04/status/reversed Response: Output will contain the list of one specific transaction or more. 7

8 [ ] "pbsno": 24997, "debgrno": 95623, "customerno": " CUST04", "date": "011213", "orderno": , "transactionid": "2d3dc50b429d44b0a9c28640c4a2c718", "transactionstatus": "PAID" "amount": "DKK 1.000,15", "pbsno": 24997, "debgrno": 95623, "customerno": " CUST04", "date": "010213", "orderno": , "transactionid": "f1d50bf2a74f4f058c688b1c3ff77af7", "transactionstatus": "RESERVED" "amount": "DKK 412,00", "pbsno": 24997, "debgrno": 95623, "customerno": " CUST04", "date": "031213", "orderno": , "transactionid": "142cfaee908e4872b48dcb67fc030416", "transactionstatus": "REVERSED" "amount": "DKK 9,99" Error handling If the user has requested a Web service that does not exist, or provided a wrong set of parameters, he will receive a general 404 http response If service path as well as provided parameters are ok, but there is no data to return a 204 http response will be returned If service path as well as provided parameters are ok, but during execution an error occurs, then the service will return an error object with code and description fields "code": -1, "description": "Invalid date range, expected range must not exceed 1 year, got: " 8

9 5.2 First time transaction(s) status service Description The web service provides information about the status of first-time payment transaction for specified creditor and debtor. Input parameters /bsexpress/rest/cardpaymentfirst/status/pbsno/debgrno/ customerno/customerno/creditorreference/creditorreference/orderno/orderno * One of OrderNo and CreditorReference should be specified. Output parameters Client will receive one or many JSON objects [pbsno, debgrno, customerno, orderno, creditorreference, statuscode] Example Requests: /bsexpress/rest/cardpaymentfirst/status/24997/95623/ exp02/orderno/ /bsexpress/rest/cardpaymentfirst/status/24997/95623/ exp02/creditorreference/pt9956ex2 Response: Output will contain the list of one specific transaction or more. "pbsno": 24997, "debgrno": 95623, "customerno": " EXP02", "orderno": , "creditorreference": "PT9956EX2", "statuscode": "RESERVED" "amount": "DKK 1.099,99" Error handling If user has requested a Web service that does not exist, or provided a wrong set of parameters, he will receive a general 404 http response. If both service path and provided parameters are ok, but there is no data to return, a 204 http response will be returned. If both service path and provided parameters are ok, but during execution an error occurs, error response with code and description fields will be returned. "code": -1, "description": "Value '10110%' of parameter 'orderno' is not a valid Number" 9

10 5.3 AUTH transaction service Description The web service provides a list of first-time payment transactions, for which reservation was made within recent 19 days and haven't been captured yet. Output results will be sorted with the most recent on top. Input parameters /bsexpress/rest/cardpaymentfirst/reservations/pbsno/debgrno Output parameters Client will receive one or many JSON objects [pbsno, debgrno, customerno, reservationdate, cardexpirydate, creditorreference, orderno] Example Request: /bsexpress/rest/cardpaymentfirst/reservations/24997/95623 Response: Output will contain the list of one specific transaction or more. "pbsno": 24997, "debgrno": 95623, "customerno": " CUST04", "reservationdate": "011213", "cardexpirydate": "0122", "creditorreference": "PT9956EX2", "orderno": "amount": "DKK 100,00", "pbsno": 24997, "debgrno": 95623, "customerno": " CUST04", "reservationdate": "111213", "cardexpirydate": "1221", "creditorreference": "PT9920STN", "orderno": "amount": "DKK 9,09", "pbsno": 24997, "debgrno": 95623, "customerno": " CUST04", "reservationdate": "111213", "cardexpirydate": "0222", "creditorreference": "PT9924STD", "orderno": "amount": "DKK 2.500,10" 10

11 Error handling If the user has requested a Web service that does not exist, or provided a wrong set of parameters, he will receive a general 404 http response If service path as well as provided parameters are ok, but there is no data to return a 204 http response will be returned If service path as well as provided parameters are ok, but during execution an error occurs, then the service will return an error object with code and description fields "code": -1, "description": "Value '2$' of parameter 'debgrno' is not a valid Number" 5.4 Cancel AUTH transactions service Description The web service allows creditor to initiate a cancellation of reservation for first-time payment transaction, to remove a reservation for a specific transaction and given customer. Input parameters /bsexpress/rest/cardpaymentfirst/reservation/cancel/pbsno/debgrno/kundenummer/ OrderNo Output parameters Client will receive one JSON object message in case of success Name Description Format message Result message of the cancelled operation, "Annul succeeded" String In case of exception, an error JSON object will be returned (see below) Examples Request: bsexpress/rest/cardpaymentfirst/reservation/cancel/24997/95682/ exp02/ Response (success): "message": "Annul succeeded" 11

12 Error handling If user has requested a Web service that does not exist, or provided a wrong set of parameters, then he will receive a general 404 http response. If service path as well as provided parameters are ok, but during execution an error occurs, then the service will return an error object with code and description fields. In case of input parameter validation exception (e.g. accidently typed symbol in DebGrNo or OrderNo) response will contain JSON object with code "-1" and detailed description of failed parameter as a message. In case if no data was found (e.g. OrderNo doesn't exist for used DebGrNo, PbsNo and CustomerNo) response will have code "-2" and text "Payment not found". In case if Netaxept returned error while actually processing the payment response will consist of code "-3" and text with error from Netaxept. In case of any other internal Netaxept error response will be "-500" as a code and details in text. "code": -1, "description": "Value '124997$' of parameter 'pbsno' is not a valid Number." "code": -2, "description": "Payment not found" "code": -3, "description": "Netaxept error occurs: Unable to annul, wrong state" 12

13 5.5 Capture AUTH transactions service Description The web service allows creditor to initiate a capture operation on reservation for firsttime payment transaction, to capture payment reservation for a specific transaction and given customer. Input parameters /bsexpress/rest/cardpaymentfirst/reservation/capture/pbsno/debgrno/kundenummer/ OrderNo Output parameters Client will receive one JSON objects code, message Name Description Format message Result message of the capture operation, "Capture succeeded" String In case of exception, an error JSON object will be returned (see below). Examples Request: bsexpress/rest/cardpaymentfirst/reservation/capture/24997/95682/ exp02/ Response (success): "message": "Capture succeeded" Error handling If user has requested a Web service that does not exist, or provided a wrong set of parameters, then he will receive a general 404 http response If service path as well as provided parameters are ok, but during execution an error occurs, then the service will return an error object with code and description fields In case of input parameter validation exception (e.g. accidently typed symbol in DebGrNo or OrderNo) response will contain JSON object with code "-1" and detailed description of failed parameter as a message In case if no data was found (e.g. OrderNo doesn't exist for used DebGrNo, PbsNo and CustomerNo) response will have code "-2" and text "Payment not found" In case if Netaxept returned error while actually processing the payment response will consist of code "-3" and text with error from Netaxept In case of any other internal Netaxept error response will be "-500" as a code and details in text 13

14 "code": -1, "message": "Value '2!' of parameter 'debgrno' is not valid Number." "code": -2, "message": "Payment not found" "code": -3, "message": "Netaxept error occurs: Transaction amount must be greater than zero." 14

15 5.6 Credit transaction service Description The web service allows creditor to initiate a credit operation on completed first-time payment transaction, to reverse payment for a specific transaction and given customer. Input parameters /bsexpress/rest/cardpaymentfirst/credit/pbsno/debgrno/kundenummer/orderno Output parameters Client will receive one JSON objects code, message Name Description Format message Result message of the credit operation, "Credit succeeded" String In case of exception, an error JSON object will be returned (see below) Examples Request: bsexpress/rest/cardpaymentfirst/credit/24997/95682/ exp02/ Response (success): "message": "Credit succeeded" Error handling If user has requested a Web service that does not exist, or provided a wrong set of parameters, then he will receive a general 404 http response If service path as well as provided parameters are ok, but during execution an error occurs, then the service will return an error object with code and description fields. In case of input parameter validation exception (e.g. accidently typed symbol in DebGrNo or OrderNo) response will contain JSON object with code "-1" and detailed description of failed parameter as a message. In case if no data was found (e.g. OrderNo doesn't exist for used DebGrNo, PbsNo and CustomerNo) response will have code "-2" and text "Payment not found". In case if Netaxept returned error while actually processing the payment response will consist of code "-3" and text with error from Netaxept. 15

16 In case of any other internal Netaxept error response will be "-500" as a code and details in text "code": -1, "description": "Value '10888(' of parameter 'orderno' is not a valid Number." "code": -2, "description": "Payment not found" "code": -3, "description": "Netaxept error occurs: Transaction amount must be greater than zero." 16

17 5.7 List temporary customer numbers Description The web service allows to retrieve information about mandates that have temporary generated CustomerNo. Input parameters /bsexpress/rest/cardmandatetempno/status/pbsno/debgrno/from/to * If the dates are not set, then all relevant card mandates will be returned. Time range can be set up to exact time in format DDMMYYYYhhmm, or without it DDMMYYYY. If the time range is set with time (hours/minutes), then these will be used, otherwise all active mandates will be returned for the full date, from/to midnight. Output parameters Client will receive one or many JSON objects [pbsno, debgrno, customerno, DebtorName, address, postalcode, city] Example Requests: /bsexpress/rest/cardmandatetempno/status/24997/2/ / /bsexpress/rest/cardmandatetempno/status/24997/2/ / /bsexpress/rest/cardmandatetempno/status/24997/2 Response: Output will contain the list of one specific mandate or more. [ "pbsno": 24997, "debgrno": 95623, "customerno": " EXP02", "debtorname": "Niels Holm", "address": "Industrivænget 2,2 tv", "postalcode": 9000, "city": "Aalborg" ] Error handling If user has requested a Web service that does not exist, or provided a wrong set of parameters, he will receive a general 404 http response 17

18 If service path as well as provided parameters are ok, but there is no data to return a 204 http response will be returned If service path as well as provided parameters are ok, but during execution an error occurs, the service will return an error object with code and description fields "code": -1, "description": "Value '2499%' of parameter 'pbsno' is not a valid Number." 18

19 5.8 Debtors contacts service Description Web service that provides information about registered mandates for defined debtor Input parameters /bsexpress/rest/cardmandate/contacts/pbsno/kundenummer Output parameters JSON array of [debgrno, customerno, mandatetype, mandatestatus] Example Request: /bsexpress/rest/cardmandate/contacts/ / adf Response: "debgrno": 1, "customerno": "CARD25", "mandatetype": "UBS", "mandatestatus": "ACTIVE", "debgrno": 2, "customerno": "CARD25", "mandatetype": "OCA", "mandatestatus": "CANCELLED" Error handing If user has requested a Web service that does not exist, or provided a wrong set of parameters, then he will receive a general 404 http response If service path as well as provided parameters are ok, but during execution an error occurs, then the service will return an error object with code and description fields "code": -1, "description": "Value '214036@' of parameter 'pbsno' is not a valid Number." 19

20 5.9 Card mandate status service Description Web service that provides information about current status of registered Card Mandates Input parameters /bsexpress/rest/cardmandate/status/pbsno/debgrpno/kundenummer /bsexpress/rest/cardmandate/status/pbsno/kundenummer Output parameters Client will receive one or many JSON objects [debgrno, customerno, mandatestatus] depending on debgrno parameter Example Request: /bsexpress/rest/cardmandate/status/24997/2/ /bsexpress/rest/cardmandate/status/24997/ Response: If debgrno provided in input parameters "debgrno": "2", "customerno": " CUST04", "mandatestatus": "ACTIVE" If debgrno is not provided in input parameters, response contains following info: [ "debgrno": "2", "customerno": " CUST04", "mandatestatus": "ACTIVE", "debgrno": "1", "customerno": " CUST04", "mandatestatus": "CANCELLED", "debgrno": "1", "customerno": " CUST04", "mandatestatus": "EXPIRED" 20

21 Error handing If user has requested a Web service that does not exist, or provided a wrong set of parameters, then he will receive a general 404 http response If service path as well as provided parameters are ok, but during execution an error occurs, the service will return an error object with code and description fields "code": -1, "description": "Value ' CUST04&' of parameter 'customerno' is not alphanumeric string." 21

22 5.10 Transaction status service Description The web service provides information about the status of payment transactions for a defined debtor. Optionally order number can be also provided. Input parameters /bsexpress/rest/cardpayment/statuses/pbsno/kundenummer/orderno Output parameters Client will receive one or many JSON objects [debgrno, customerno, mandatestatus] depending on debgrno parameter Example Request: /bsexpress/rest/cardpayment/statuses/24997/ exp02/777 /bsexpress/rest/cardpayment/statuses/24997/ exp02 Response: Response contains the list of transaction (s): "debgrno": 1, "customerno": " EXP02", "orderno": 777, "statuscode": "INIT", "debgrno": 1, "customerno": " EXP02", "orderno": 778, "statuscode": "CANCL", "debgrno": 1, "customerno": " EXP02", "orderno": 888, "statuscode": "INIT", "debgrno": 1, "customerno": " EXP02", "orderno": 889, "statuscode": "FAIL", "debgrno": 1, "customerno": " EXP02", "orderno": 999, "statuscode": "INIT" 22

23 Error handing If user has requested a Web service that does not exist, or provided a wrong set of parameters, he will receive a general 404 http response If service path as well as provided parameters are ok, but during execution an error occurs, the service will return an error object with code and description fields "code": -1, "description": "Value '24457$' of parameter 'pbsno' is not a valid Number." 23

24 5.11 Active mandates service Description The web service provides information about creditors active mandates, registered in BS Express Input parameters /bsexpress/rest/cardmandate/active/pbsno Output parameters JSON array of [debgrno, customerno, mandatetype, mandatestatus] Example Request: /bsexpress/rest/cardmandate/active/24997 Response: Response contains the list of active card mandates: "debgrno": "1", "customerno": " EXP02", "mandatetype": "OCA", "cardexpirydate": "0114", "mandateregdate": "111113", "debgrno": "1", "customerno": " CUST010", "mandatetype": "OCA", "cardexpirydate": "0117", "mandateregdate": "301013", "debgrno": "1", "customerno": " CUST05", "mandatetype": "OCA", "cardexpirydate": "0122", "mandateregdate": "300913", "debgrno": "2", "customerno": " CUST04", "mandatetype": "OCA", "cardexpirydate": "0122", "mandateregdate": "300913", "debgrno": "1", "customerno": " EXP02", "mandatetype": "OCA", "cardexpirydate": "0114", "mandateregdate": "300913" 24

25 Error handing If the user has requested a Web service that does not exist, or provided a wrong set of parameters, then he will receive a general 404 http response If service path as well as provided parameters are ok, but during execution an error occurs, the service will return an error object with code and description fields "code": -1, "description": "Value '124997$' of parameter 'pbsno' is not a valid Number." 25

26 5.12 Outstanding payments service Description The web service provides information about creditors outstanding payments for the defined period. Input parameters /bsexpress/rest/cardpayment/outstanding/pbsno/kundenummer/from/to /bsexpress/rest/cardpayment/outstanding/pbsno/from/to /bsexpress/rest/cardpayment/outstanding/pbsno/from /bsexpress/rest/cardpayment/outstanding/pbsno Output parameters Client will receive one/many JSON objects [customerno, orderno, debgrnr, paymentduedate, amount] Example Request: /bsexpress/rest/cardpayment/outstanding/24997/ exp02/011113/ Response: Response contains the list of transaction (s): "customerno": " EXP02", "orderno": 888, "debgrno": 1, "paymentduedate": "141113", "amount": " DKK", "customerno": " EXP02", "orderno": 777, "debgrno": 1, "paymentduedate": "131113", "amount": " DKK" The list contains transactions ordered by new_due_date, beginning with the latest Error handing If user has requested Web service that does not exist, or provided wrong set of parameters, he will receive general 404 http response If service path as well as provided parameters are ok, but during execution some error occurs, then service will return error object with code and description fields "code": -1, "description": "Value '1234%' of parameter pbsno' is not a valid Number." 26

27 5.13 Transaction history service Description The web service provides information about creditors payment transactions for the defined period Input parameters /bsexpress/rest/cardpayment/history/pbsno/from/to Output parameters Client will receive one or many JSON objects debgrnr, customerno, orderno, statuscode, originalduedate, searchdatefrom, searchdateto Example Request: /bsexpress/rest/cardpayment/history/ /131112/ Response: Response contains the list of transaction (s): [ "debgrno": 1, "customerno": " CUST08", "orderno": 891, "statuscode": "INIT", "originalduedate": "131113", "searchdatefrom": "131112", "searchdateto": "131113", "debgrno": 1, "customerno": " EXP02", "orderno": 777, "statuscode": "INIT", "originalduedate": "131113", "searchdatefrom": "131112", "searchdateto": "131113", "debgrno": 1, "customerno": " EXP02", "orderno": 778, "statuscode": "CANCL", "originalduedate": "131113", "searchdatefrom": "131112", "searchdateto": "131113", "debgrno": 1, "customerno": " EXP02", "orderno": 889, 27

28 ] "statuscode": "FAIL", "originalduedate": "131113", "searchdatefrom": "131112", "searchdateto": "131113", "debgrno": 1, "customerno": " EXP02", "orderno": 999, "statuscode": "INIT", "originalduedate": "131113", "searchdatefrom": "131112", "searchdateto": "131113", "debgrno": 1, "customerno": " CUST010", "orderno": 890, "statuscode": "INIT", "originalduedate": "131113", "searchdatefrom": "131112", "searchdateto": "131113" Error handing If user has requested Web service that does not exist, or provided wrong set of parameters, then he will receive general 404 http response If service path as well as provided parameters are ok, but during execution an error occurs, then the service will return an error object with code and description fields "code": -1, "description": "Invalid date range, expected range must not exceed 1 year, got: " 28

29 5.14 Expiring card service Description The web service provides a list of card mandates, which will expire in defined period, or, if the period is not specified, within the nearest two months. Input parameters /bsexpress/rest/cardmandate/expiry/pbsno/kundenummer/from/to /bsexpress/rest/cardmandate/expiry/pbsno/kundenummer/from /bsexpress/rest/cardmandate/expiry/pbsno/kundenummer Output parameters Client will receive one/many JSON objects [debgrno, customerno, mandatestatus, cardexpirydate, cardno] Example Request: /bsexpress/rest/cardmandate/expiry/24997/ cust04/1113/1222 Response: "debgrno": "1", "customerno": " CUST04", "mandatestatus": "CANCELLED", "cardexpirydate": "0122", "cardno": "4925xxxxxxxx0004", "debgrno": "1", "customerno": " CUST04", "mandatestatus": "EXPIRED", "cardexpirydate": "1221", "cardno": "4925xxxxxxxx0004", "debgrno": "2", "customerno": " CUST04", "mandatestatus": "ACTIVE", "cardexpirydate": "0222", "cardno": "4925xxxxxxxx0079" Error handing If the user has requested a Web service that does not exist, or provided a wrong set of parameters, he will receive a general 404 http response. If service path and provided parameters are ok, but during execution an error occurs, then the service return an error object with code and description fields. "code": -1, "description": "Value '1234%' of parameter 'pbsno' is not a valid Number." 29

30 5.15 Transaction credit service Description The web service allows creditor to initiate a credit transaction, to reverse a payment for a specific transaction and given customer. Input parameters /bsexpress/rest/cardpayment/credit/pbsno/kundenummer/orderno Output parameters Client will receive one JSON objects code, message Name Description Format code Result code of the operation: CREDITED or FAILED String message Result message of the credit operation String Example Request: bsexpress/rest/cardpayment/credit/24997/ exp02/999 Response: Response contains the following: "code": "CREDITED", "message": "Successfully credited" Error handing If user has requested a Web service that does not exist, or provided a wrong set of parameters, then he will receive a general 404 http response If service path as well as provided parameters are ok, but during execution an error occurs, then the service will return an error object with code and description fields "code": -2, "description": "Payment not found, it may be already credited" 30

31 5.16 Incomplete payment service from the Tast-selv module Description This service is used by Operator to get list of all incomplete and unsuccessful transactions (CARDSYS, IVRERR), when creditor is using Automatic card payments Tast-selv module. Input parameters /bsexpress/rest/telemarketing/incompletetransactions/pbsno/debgrno/from/to Output parameters Client will receive one or many JSON objects pbsno, debgrnr, customerno, transactionid, timestamp, response, responsecode, responsesource, ivrerrortext, debtorphoneno Name Description Format pbsno Creditors ID with Nets Integer debgrnr The debtor Group number that the customer is enrolled to Integer customerno Creditors ID for the debtor Integer transactionid ID for transaction in NetAxept String timestamp Date the request was created Timestamp dd-mm-yyyy hh:mm:ss response Identify the level where error occurred (CARDSYS, IVRERR,) String responsecode Error code generated by NetAxept and returned by IVR. String responsesource Cause of error generated by NetAxept or by IVR. (ex. Refused by String Issuer) ivrerrortext Error description generated by IVR String debtorphoneno Debtor phone number String referenceid Unique ID for particular day generated for each telemarketing request Integer Example Request: /bsexpress/rest/telemarketing/incompletetransactions/25000/6/110414/ Response: Response contains the list of incomplete telemarketing transactions: 0: pbsno: debgrno: 6 customerno: "ASD " transactionid: "142cfaee908e4872b48dcb67fc030416" timestamp: " :13:34" response: "CARDSYS" responsecode: "ds" responsesource: "02" ivrerrortext: "" 31

32 ,, debtorphoneno: "AdditionalInfo" referenceid: 3 pbsno: debgrno: 6 customerno: "ASD " transactionid: "142cfaee908e4872b48dcb67fc030416" timestamp: " :15:34" response: "IVRERR" responsecode: "02" responsesource: "as" ivrerrortext: "IVR hang up" debtorphoneno: "AdditionalInfo" referenceid: 2 pbsno: debgrno: 6 customerno: "ASD " transactionid: "142cfaee908e4872b48dcb67fc030416" timestamp: " :12:24" response: "IVRERR" responsecode: "04" responsesource: "as" ivrerrortext: "Hang up due to max retry of CPR or CVR in IVR" debtorphoneno: null referenceid: 7 Error handing If user has requested web service that does not exist, or provided wrong set of parameters, then he will receive general 404 http response If SM_USER header is missing or has incorrect format or pbsno is missing then 403 https response is received. If pbsno has incorrect format then 400 https response is received. If service path as well as provided parameters are ok, but during execution an error occurs, then the service will return an error object with code and description fields "code": -1, "description": "Invalid date range, expected range must not exceed 1 year, got: " 32