Requests that are forwarded via redirects by a customer's web browser are authenticated via browser API authentication.

Transcription

1 Poplatek Server API Version: Quick links Browser API Pay REST API Get Transaction Status Cancel Refund Settlement report Changes : Document sandbox URL endpoints. Small miscellaneous fixes : Rename Server API => REST API, and Payment API => Server API : Document field sales_location_id in "Settlement report" response : Add a full example of "Settlement report" response. Browser API Browser API currently includes only an ecommerce payment API. Poplatek payment API is an integration API for payment providers wishing to do ecommerce credit card payments. The primary use case is allowing a customer to make a purchase with a credit card, by redirecting the customer's web browser from the payment provider site to a credit card payment form site provided by Poplatek. There the customer will be able to fill in their credit card number to a payment form and approve the payment. The payment is possibly authenticated with Visa 3-D Secure, requiring several redirects of the web browser. After payment completion the customer is redirected back to the payment provider site. In addition to the browser redirect, there is a backend server to server communication REST API which can be used for status enquiry, cancellations and refunds. In requests all fields are mandatory unless they are specifically documented to be optional. Authentication in browser API Requests that are forwarded via redirects by a customer's web browser are authenticated via browser API authentication. Both authentication and the request contents are passed by a single URL parameter, "token", which contains an encoded JSON Web Token. The algorithm to be used is HMAC-SHA-256 and the shared secret is established between Poplatek and the payment provider. Response messages are encoded similarily with a "token" URL parameter, with the issuer and audience fields swapped, and authenticated with the same shared secret. A sample token would be calculated as follows: Base64({ "typ": "JWT",

2 "alg": "HS256" }). Base64({ "iat": , "iss": "paymentprovider", "aud": "poplatek", "ext_transaction_id": "3f3a449e-b667-40c9-b674-db3f9f80f9fb",... other request fields... }). HMACSHA256(secret, Base64(header) + "." + Baset64(body)) Pay URL endpoint: [[br]] URL endpoint for testing: This request is used to initiate a purchase. The customer should be redirected to the URL endpoint with a token parameter generated by originating server. The customer will be presented with a payment page where he will see the merchant name and the payment amount and where he can input a credit card number and other relevant information. After the purchase action is completed, the customer browser will be redirected back to one of the three destination URLs, with a token parameter describing the result of the purchase. Because the response is authenticated, the response fields may be used directly, but must be checked rigorously to correspond to the current transaction. In most cases it is easier and safer to simply do a separate get_transaction_status query with the REST API and ignore the response fields, and it is recommended to do so. Request fields iat : Token issuing timestamp. Informational and optional, not used in processing. Specified by JWT. exp : Token expiration time. Requests arriving after this time will be rejected directly. If this is left out, tokens generated will be valid indefinitely and may be saved by the customer for later use. The use of this parameter is strongly recommended, but it is ultimately optional. Specified by JWT. nbf : Token not before time. Requests arriving before this time will be rejected directly. Optional. Specified by JWT. jti : Token identity to prevent replays. Duplicate requests arriving with the same token identity may be rejected directly, but are not guaranteed to. However, ext_transaction_id will prevent the same payment from being completed twice, even if the request is processed. Specified by JWT. iss : Issuer of the request, which should identify the payment provider. Values are agreed with each payment provider. Specified by JWT. aud : Audience of the request. If used, it should have the value by JWT. "poplatek", or a list including "poplatek". Specified ext_transaction_id : Transaction id defined by the payment provider. This will be handled as an opaque string by Poplatek and is used to uniquely identify the transaction. This should be allocated and stored in a database before sending the request so that transactional reliability can be achieved. order_id : Order id that this transaction is a part of. String. merchant_id : Merchant that the transaction is for. All merchants must configured for Poplatek before use. String. action : The desired action for the request. AUTHORIZE_AND_SETTLE : Single request flow marking the transaction directly as completed. To achieve transactional reliability, the get_transaction_status API must be used. currency : Transaction currency as a number or string as specified by ISO 4217, eg. 978 or "EUR" for euro. amount : Transaction amount multiplied by the decimals specified by ISO 4217, eg. amount in cents for euro. language : The currently used interface language by the customer, as a two letter code specified by ISO 639-1, eg. "fi" for Finnish.

3 order_description : Freeform order description. May be shown to the customer, and will be retained in logs but not processed programmatically. reject_unauthenticated : Disallow purchases that cannot be authenticated via Visa 3-D Secure or similar technology. This has implications for merchant risk. Boolean, false if not present. prefer_unauthenticated : Prefer not using Visa 3-D Secure or similar technology for authentication if transaction can be completed without it. This has implications for merchant risk. Boolean, false if not present. allowed_card_schemes : A list of one or more card schemes that the purchase is permitted to be completed with. If this field is not used, all schemes are allowed. List items are as following: VI : Visa and Visa Electron MC : MasterCard and Maestro AX : American Express DC : Diners Club JC : Japan Credit Bureau UP : China UnionPay card_scheme : Card scheme the purchase is meant to be completed with, but user can use any other scheme permitted by allowed_card_schemes. Response includes which scheme was used for actual payment. Optional. success_url : The URL the browser will be redirected to after a successful payment. A appended to this containing the response token. token parameter will be failure_url : The URL the browser will be redirected to after a failed payment. A token parameter will be appended to this containing the response token. This URL is only used when user has entered the card information and attempted to make the payment. In the following error situations an error message is shown to user, and the browser is not directed to any URL: User interface and backend database have a mismatch, most likely because the user has used the browser back button or otherwise caused invalid UI flow. Token content or format is invalid. Configuration error, for example merchant is not permitted. An internal technical error has occurred, for example a network timeout. cancel_url : The URL the browser will be redirected to after a cancelled payment. A token parameter will be appended to this containing the response token. This URL is only used when user requests payment cancellation, and get_transaction_status will show the purchase as having been cancelled. If user requests payment cancellation, but purchase has already been confirmed or has failed, an error message is shown to user, and the browser is not redirected to any URL. Response fields iat : Token issuing timestamp. Informational. May not be always present. Specified by JWT. exp : Token expiration time. Requests arriving after this time MUST be rejected. May not be always present. Specified by JWT. nbf : Token not before time. Requests arriving before this time MUST be rejected. May not be always present. Specified by JWT. jti : Token identity to prevent replays. This may be used to reject duplicate requests arriving with the same token identity. May not be always present. Specified by JWT. iss : Issuer of the request, which identifies that request is from Poplatek. Contains the value JWT. "poplatek". Specified by aud : Audience of the request, which identifies the payment provider. Will not be sent right now to avoid compatibility issues with non-conforming JWT implementations. Shared secret and issuer are used to assume audience. Specified by JWT.

4 destination_url : The destination URL (not including the token parameter) the browser was redirected to by Poplatek. If any state changing actions are performed by parsing the response, this parameter MUST be verified to match the current URL. It is very easy to change a failure URL in to a success URL in the browser. Additionally a response token contains some of the fields listed under "Common transaction response fields" below as following. Successful request: All of the fields are included. These give the complete state of the transaction. Cancelled request: The following fields: ext_transaction_id, status_code, browser_ip_country, browser_ip_country_alpha Failed request: Unspecified. Response may also contain other fields that are not specified in this document. Such fields should be ignored. REST API REST API requests use HTTPS POST method, with both the request and the response as JSON in the body. Requests should contain the following HTTP headers: Content-Type: application/json Accept: application/json Example request body: { } "ext_transaction_id": "3f3a449e-b667-40c9-b674-db3f9f80f9fb" Example response body (only a subset of normal response fields shown): { "ext_transaction_id": "3f3a449e-b667-40c9-b674-db3f9f80f9fb", "amount": 3000, "currency": 978, "referring_transactions": [234, 345, 456] } All responses may contain additional fields not specified in this document. Such fields should be ignored. In requests all fields are mandatory unless they are specifically documented to be optional. Authentication in REST API SSL certificate verification is used for server authentication, and simple HTTP basic authentication with username and password is used for client authentication. Other authentication types will be added later. Error reporting Errors are reported primarily by HTTP status codes, with 2xx for success, 4xx for client errors and 5xx for server errors. Note that even if the request is successful (returning a 2xx status), the transaction created might be rejected (having success as false and status_code as something other than SUCCESS ). The response will contain the following fields: error_code : A string code for the error triggered. The list of codes evolves with time, but it is relatively stable. If there are reasons to provide users specific feedback on some errors, localized error messages should be mapped based on this code alone. error_description : An english human readable description for the error, which may provide more information than simply the error_code. This should not be presented to the user directly, but may be retained in logs and administration interfaces for information. Optional. error_details : A stack traceback and other verbose context information about the error, if available. Optional.

5 Example error: { "error_code": "USER_CANCELLED", "error_description": "User cancelled the transaction.", "error_details": "..." } Get Transaction Status URL endpoint: URL endpoint for testing: This request can be used to query the current status of a transaction. The transaction in question can be referenced either by ext_transaction_id or by transaction_id. If both are given, transaction_id is used. The transaction status is guaranteed to be up to date with recent transactions and even ongoing transactions, but may obviously change after querying. Request fields ext_transaction_id : Transaction id given by the payment provider. This means of referring a transaction will look up the transaction based on both the identifier given and the identity of the requesting party. transaction_id : Transaction id assigned by Poplatek and returned on requests. This identifier space is global for all transactions processed by Poplatek. Response fields Only the common transaction fields are included, listed below. Cancel URL endpoint: URL endpoint for testing: This request is used to cancel a transaction completely. The customer will not be charged for the transaction after cancellation and any reserved funds will be freed. Cancellation for a partial amount is not supported. The cancel request will also succeed for requests that have not been seen before by Poplatek. This is to ensure that transactional reliability can be achieved even if cancellation is done before the payment request token expires. In this case the cancellation will ensure that no future requests with the same ext_transaction_id can succeed. Cancellation is not possible for transactions which have already been settled with the acquirer. Such transactions will have to be refunded instead. Request fields ext_transaction_id : Transaction id given by the payment provider. This means of referring a transaction will look up the transaction based on both the identifier given and the identity of the requesting party. transaction_id : Transaction id assigned by Poplatek and returned on requests. This identifier space is global for all transactions processed by Poplatek. order_id : Order id of the transaction being cancelled. merchant_id : Merchant whose transaction is being cancelled. reason_code : A string code for the cancellation reason. USER_CANCELLED : Customer cancelled the purchase by his own action. TIMEOUT : Some timeout was triggered during purchase processing and the purchase was cancelled. MERCHANT_CANCELLED : Merchant decided to cancel the purchase. UNKNOWN : Other cancellation reason, description should be used to specify which. Other codes can be used, but should be agreed with Poplatek.

6 reason_description : A human readable description of the cancellation reason. This will not be presented to the user, but will be shown in logs and administrative interfaces. May be specified by the merchant. Optional. Response fields If successful, the transaction status_code should be CANCELLED. The returned success field will show false as the transaction in question is no longer successful. This does not mean that the cancellation request failed. Only the common transaction fields are included, listed below. Refund URL endpoint: URL endpoint for testing: This request will create a new refund transaction. The original purchase that this refund is for must be identified to be able to create a refund. This original transaction can be referenced either by original_ext_transaction_id or by original_transaction_id. If both are given, original_transaction_id is used. Also the sum of all refunds for a purchase transaction must not exceed the original amount of the purchase transaction. Request fields ext_transaction_id : Refund transaction id defined by the payment provider. This will be handled as an opaque string by Poplatek and is used to uniquely identify the refund transaction. This should be allocated and stored in to a database before sending the request so that transactional reliability can be achieved. order_id : Order id that this refund transaction is a part of. merchant_id : Merchant that the refund transaction is for. All merchants must configured for Poplatek before use. original_ext_transaction_id : Transaction id of the original purchase transaction given by the payment provider. This means of referring a transaction will look up the transaction based on both the identifier given and the identity of the requesting party. original_transaction_id : Transaction id of the original purchase transaction assigned by Poplatek and returned on requests. This identifier space is global for all transactions processed by Poplatek. reason_code : A string code for the refund reason. MERCHANT_REFUND : Merchant decided to refund a part of the purchase or the full purchase. The reason for this may be product returns, inability to deliver or some other reason. UNKNOWN : Other refund reason, description should be used to specify which. Other codes can be used, but should be agreed with Poplatek. reason_description : A human readable description of the refund reason. This will not be presented to the user, but will be shown in logs and administrative interfaces. May be specified by the merchant. Optional. currency : Transaction currency as a number or string as specified by ISO 4217, eg. 978 or "EUR" for euro. This must match the original purchase currency. amount : The amount to be refunded. This may be equal to or smaller than the current refundable amount for the purchase transaction. Response fields Only the common transaction fields are included. Settlement report URL endpoint: URL endpoint for testing: This request returns settlement batches and their transactions for given day. Failed transactions are not present in any batch.

7 Report requests use HTTPS GET method. Request parameters are passed as URL parameters. Response is JSON as in other REST API endpoints. Requests should contain the following HTTP header: Accept: application/json Request fields date : Creation date of the settlement batches, eg Z. Example request URL (there is no request body): Response fields Top level of the response contains a list of settlement batches, of which each contains its transactions. Example response with one settlement batch that contains two transactions: [{ "creation_time" : " T22:30:00Z", "currency" : 978, "currency_alpha" : "EUR", "feedback_status" : "UNKNOWN", "merchant_id" : "example-merchant", "merchant_number" : " ", "purchases_amount" : 6599, "purchases_count" : 2, "reference_number" : null, "refunds_amount" : 0, "refunds_count" : 0, "sales_location_id" : 40050, "settlement_batch_id" : "517", "state" : "DELIVERED", "transactions" : [{ "amount" : 2000, "authenticated" : false, "authentication_result" : "UNATTEMPTED", "authorized" : true, "browser_ip_country" : 246, "browser_ip_country_alpha" : "FI", "card_country" : 246, "card_country_alpha" : "FI", "card_currency" : 978, "card_currency_alpha" : "EUR", "card_scheme" : "VI", "currency" : 978, "currency_alpha" : "EUR", "customer_pan" : "************7408", "emv_reference_number" : " ", "emv_terminal_id" : " ", "emv_transaction_time" : " ", "end_timestamp" : " T07:53:14Z", "ext_transaction_id" : "331e6df9-650e-5e45-7b fb", "merchant_id" : "1510", "merchant_pan" : "426801******7408", "order_id" : "123abc", "start_timestamp" : " T07:53:08Z", "status_code" : "SUCCESS", "status_description" : "payment terminal confirmed transaction as successful", "success" : true, "transaction_id" : " ", "type" : "PURCHASE" }, { "amount" : 4599, "authenticated" : false, "authentication_result" : "UNATTEMPTED", "authorized" : true, "browser_ip_country" : null, "browser_ip_country_alpha" : null, "card_country" : 246, "card_country_alpha" : "FI", "card_currency" : 978,

8 "card_currency_alpha" : "EUR", "card_scheme" : "VI", "currency" : 978, "currency_alpha" : "EUR", "customer_pan" : "************1234", "emv_reference_number" : " ", "emv_terminal_id" : " ", "emv_transaction_time" : " ", "end_timestamp" : " T08:01:28Z", "ext_transaction_id" : null, "merchant_id" : null, "merchant_pan" : "426899******1234", "order_id" : null, "start_timestamp" : " T08:01:22Z", "status_code" : "SUCCESS", "status_description" : "payment terminal confirmed transaction as successful", "success" : true, "transaction_id" : " ", "type" : "PURCHASE" }] }] Settlement batch levels fields creation_time : Timestamp when the batch was created, in UTC. Eg T21:30:01Z. currency : Currency of the settlement batch as a number as specified by ISO 4217, eg. 978 for euro. currency_alpha : Currency of the settlement batch as a string as specified by ISO 4217, eg. "EUR" for euro. feedback_status : Status of batch feedback reception from acquirer: ACCEPTED : Acquirer has accepted the batch. UNKNOWN : Acquirer has not yet given feedback. Other values may be present which represent various feedback errors. merchant_id : Merchant's ID. String. merchant_number : Acquirer provided number specifying the merchant and location for settlements. In Nets terminology, for example, this is called "liiketunnus". String. purchases_amount : Total amount of purchases, multiplied by the decimals specified by ISO 4217, eg. total amount in cents for euro. purchases_count : Count of purchases in the batch. reference_number : Creditor reference of settlement batch, if known. Format is undefined. String. refunds_amount : Total amount of refunds, multiplied by the decimals specified by ISO 4217, eg. total amount in cents for euro. refunds_count : Count of refunds in the batch. sales_location_id : Each terminal belongs to a sales location, which typically represents a physical location such as a store. Numeric. settlement_batch_id : Poplatek unique settlement batch id for the settlement batch. String. state : DELIVERED if the batch has been delivered to acquirer. Otherwise PENDING. Transaction level fields Transaction level contains for each transaction all the common transaction response fields, defined below, except for refundable_amount and referring_transactions. Common formats Common transaction response fields

9 state ext_transaction_id : Transaction id given in the request by the payment provider. It is suggested that this is allocated as an universally unique identifier. String. order_id : Order id that this transaction is a part of. String. merchant_id : Merchant that the transaction is for. String. transaction_id : Poplatek unique transaction id for the transaction. String. type : A string code giving the type of this transaction. PURCHASE : A purchase transaction, also called sale or debit. REFUND : A refund transaction, sometimes called cancellation, reversal, void or credit. success : Boolean flag telling whether transaction was successful or not. status_code : A string code describing the status of the transaction giving a more detailed error code for failures. Only some examples are specified here. IN_PROGRESS : Transaction processing has not yet completed. status_code will likely later change to some other value, and other fields are likely missing. If value is anything else, it will not change anymore, except if the transaction is cancelled. SUCCESS : Successful transaction. USER_CANCELLED : The user decided to cancel the transaction. TIMEOUT : User didn't complete or cancel the transaction quickly enough. AUTHORIZATION_ROUTING : Card BIN range not supported. status_description : An english human readable description of transaction status. This should not be presented to the user, but may be retained in logs and administration interfaces for debugging. currency : Transaction currency as a number as specified by ISO 4217, eg. 978 for euro. currency_alpha : Transaction currency as a string as specified by ISO 4217, eg. "EUR" for euro. amount : Transaction amount multiplied by the decimals specified by ISO 4217, eg. amount in cents for euro. merchant_pan : Card number formatted for the merchant. Complies with PCI regulations in not exposing more than the allowed number of digits. customer_pan : Card number formatted for customer display. Complies with PCI regulations in what is to be shown on customer receipts. authorized : Boolean flag if a payment authorization was done on the payment. For ecommerce, authorization is mandatory, so this will be true for all successful transactions. authenticated : Boolean flag telling whether Visa 3-D Secure or similar authentication was performed successfully. false means either failed authentication or authentication not performed. authentication_result : String code describing the result of 3-D Secure or similar authentication. SUCCESS : Authentication was performed successfully. UNATTEMPTED : Authentication was not attempted at all. Other codes will be clarified later on. card_scheme : Card scheme corresponding to the card number the transaction was actually performed with. Same values as in request. card_country : Card country specified as ISO numeric-3 code. Should be present and correct for most Visa and MasterCard cards, but can be missing or incorrect. Can be used for risk management. card_country_alpha : Card country specified as ISO alpha-2 code. See card_country.

10 card_currency : Native currency of cardholder account as specified by ISO 4217 numeric. Should be present and correct for most Visa and MasterCard cards, but can be missing or incorrect. Can be used for risk management. card_currency_alpha : Native currency of cardholder account as specified by ISO 4217 string, eg. "EUR" for euro. See card_currency. browser_ip_country : Pay request origin country specified as ISO numeric-3 code. This is resolved from the cardholder browser IP address and may not always be correct or present. browser_ip_country_alpha : Pay request origin country specified as ISO alpha-2 code. See browser_ip_country. Notice that United Kingdom has code GB rather than UK. refundable_amount : This is the amount left that can still be refunded on this transaction. The sum of all refunds is not allowed to exceed the original amount. referring_transactions : List of transaction_id values that refer to this transaction. Currently every referring transaction is a refund, but there might be other types later on. For new purchase transactions this list is always empty. start_timestamp : ISO 8601 timestamp of the transaction creation time. String. end_timestamp : ISO 8601 timestamp of the the time the processing of the transaction has completed. String. emv_transaction_time : YYmmddHHMMSS format timestamp used in the financial transaction to the bank. String. emv_reference_number : Twelve-digit reference number of the financial transaction. String. emv_terminal_id : Eight character long terminal identifer used in the financial transaction. String.