createPaymentRequest

HTTP method: POST

The createPaymentRequest method initiates a new payment by sending a payment request with all relevant payment information to the gateway. It is the preferred way of enabling a customer to pay via the AltaPay payment platform. It supports all the Alternative Payment Methods that are supported on our platform, and even though it redirects the customer to AltaPay, you (the merchant) keep complete control of the payment page. You can easily and dynamically adapt it so that, as far as your customer is concerned, they never leave your shop.

On receipt of the payment request, you get the payment page URL.

  • The Url element contains the URL you should direct your customers to.
  • The DynamicJavascriptUrl element contains a URL you can use to dynamically load the payment page in an iFrame. For more information, see Loading the payment page dynamically.
  • The AppUrl element contains a URL you can use to initiate the credit card wallet payment in app. For more information, see Initiate Credit Card Wallet payment in app.
Test URL https://testgateway.altapaysecure.com/merchant/API/<method>
Production URL https://<YourShopName>.altapaysecure.com/merchant/API/<method>

For information about the payment flow process, see Payment flow process (Merchant API).

The URLs show a payment page that for credit card payments, without custom styling, looks like this:

For instructions on how to create custom styling for the payment page, see Styling the payment page (callback_form).

For information about the XML Schema Definition for API responses, see API Response structure (XML).

To enable surcharging (only for credit cards) on a terminal, using specific surcharging rules, contact us.

If surcharging is disabled on your terminal, but rules have been set up, the calculateSurcharge method calculates the surcharge based on those rules. As of January 2018, surcharging consumer credit cards in the EU, Norway, and Iceland is prohibited.

Request parameters

The API call does not happen in the browser, which means that users cannot tamper, or even see, the data posted to the gateway. You do not have to pass a check sum for the customer information.

The following parameters are mandatory for all integrations:

Parameter

Description

Type

 Mandatory

terminal

The terminal determines the payment method and currency. For more information, see AltaPay's Payment Gateway. This is the title of your terminal, found under Home > Terminal Settings in the Merchant Interface. You can use variables in the terminal parameter. For example, if you want to call My EUR Terminal, you can set the terminal parameter value to 'My {currency} Terminal', where {currency} references the value of the currency parameter.

string

Yes

shop_orderid

This is the internal ID of the order in your webshop. In most integrations, you can use the same order ID for up to four orders. For PayPal, MobilePay and Vipps payments, you can only use it for a singe successful transaction. The shop_orderid value is posted back to you, so you know the order to which the payment refers.

 

[a-zA-Z0-9-]{1,100}

PayPal, MobilePay and Vipps only accept order IDs of 50 characters or less

Yes

amount

This is the payment amount. If you are setting up a subscription, it is the default amount for each capture. For unscheduled agreement you can use 0 if you are only setting up the subscription without charging the customer.
You must use a dot as the decimal separator, and the amount can have maximum 2 decimals.

float

Yes
Not required when setting up unscheduled agreement.

currency

This is the payment currency. It must be specified in an ISO-4217 format, either using the 3-digit numeric code, or the 3-letter character code. For more information about ISO-4217 currency codes, see https://en.wikipedia.org/wiki/ISO_4217.

Only allows payments in DKK or EUR.

Only allows payments in NOK

[0-9]{3} or

[A-Z]{3}

Yes

Select from the drop-down list to see the parameters relevant for that method/acquirer:

Parameter

Description

Type

 Mandatory

language

The language in which the payment form is displayed. For more information about supported language codes, see Supported languages. If the language parameter is not set, the language is derived from the browser's Accept-Language HTTP header field. If none of the browser languages are supported, the default is English, en. If the language you set is not supported, an error is returned.

[a-z]{2}

 
transaction_info

This is a one-dimensional associative array, where you can put any value that you would like to associate with the payment in the call to createPaymentRequest.

Array

Maximum 50 entries of maximum 255 characters each.

 

type

This is the authorization type. For more information, see Payment request types:

  • payment (default)
  • paymentAndCapture
  • verifyCard
  • credit
  • subscription
  • subscriptionAndCharge
  • subscriptionAndReserve

It is not possible to create a payment request with type=payment.

If the type is set to payment, it is automatically changed to paymentAndCapture.

The subscriptionAndReserve type is not supported when setting up an recurring agreement.

The subscriptionAndCharge type is not supported when setting up an unscheduled agreement.

string

 

ccToken

This is the credit card token value. By using a credit card token from a previous payment, your customer won't have to enter credit card details again. To enable this, select the Enable credit card token check box under Home > Terminal Settings in the Merchant Interface.

[0-9a-f]{41}

 

sale_reconciliation_identifier

This is the sales reconciliation identifier, used in the reconciliation CSV files you can download from the Merchant Information Interface, or by using the getCustomReport method. For more information, see getCustomReport.This parameter can only be used when the type parameter is set to paymentAndCapture.

String{0,100}

 

sale_invoice_number

This is the invoice number for the capture.

String{0,100}

Do NOT set this parameter for Klarna payments

ccToken / credit_card_token

This is the credit card token from a previous payment, if this is supplied in the createPaymentRequest then the credit card will be pre-filed out with the card number and expiration month and year. ccToken and credit_card_token can both be used.

String{0,100}

Do NOT set this parameter for Klarna payments

fraud_service

Setting the fraud_service parameter lets you select a different fraud detection service on the payment level.

none

maxmind

red

test

 

cookie

This is the cookie that will be sent back to all your callback URLs. For example, if your cookie parameters are set to PHPSESSID=id1337;mycookie=mycookievalue;, the cookie header in the callback is Cookie: PHPSESSID=asdfasdfdf23; mycookie=mycookievalue

String

 

payment_source

This identifies the source of the payment.

Currently we're supporting the following sources:

Category Source of payment Technical name
POS Point of Sales
MOTO Mail Order moto
Telephone Order moto, telephone_order
Mail order Mail Order mail_order
ECOMM E-commerce eCommerce
E-payment
MOBI (Mobile) mobi
Bank Payment

The default value is eCommerce.

moto is treated as telephone_order.

Only eCommerce, mobi, moto, mail_order, telephone_order can be sent by the merchants in the PaymentSource. The rest of the values will be changed inside the gateway internally, as the transaction is being processed

eCommerce

mobi

moto

mail_order

telephone_order

 

shipping_method

Fraud detection services can use this parameter in the fraud detection calculations.

LowCost

DesignatedByCustomer

International

Military

NextDay

Other

StorePickup

TwoDayService

ThreeDayService

 

customer_created_date

This is the date when the customer account was first created in your shopping system. Fraud detection services use this parameter in the fraud detection calculations.

Date (yyyy-mm-dd)

 

organisation_number

this is the company registration number (CRN), and is used to identify the company and verify the fact that it is a entity registered with the relevant authority, for example, Companies House in the UK. Do not confuse this with the customer_info[vat_id], although in some countries the number may be the same.

To ensure that the organisation number field is pre-populated on the invoice payment form, set the organisation_number parameter.

String{0,20}

Yes, if the customer_info[type]=business

account_offer

If you set account_offer to required, the customer must have an account set up to be able to use invoice payment.

To disable the account for a specific customer, set account_offer to disabled.

required

disabled

 
sales_tax

The sales tax amount. Indicates how much of the gross amount that was sales tax, e.g. VAT (UK) or Moms (DK).

 float
Yes

This parameters should be provided only in case the type parameter is subscription, subscriptionAndCharge or subscriptionAndReserve

Parameter Description Type Mandatory
agreement[id]

This is the id of the setup agreement payment.

This should be provided only in case of charging verify card agreement.

 string No
agreement[type]

This is the type of the agreement.

In case the reservation type parameter is subscription, subscriptionAndCharge or subscriptionAndReserve and no agreement[type] is provided, it will create a recurring agreement.

Possible values:

 string  No
agreement[unscheduled_type]

This is the type of the unscheduled agreement.

In case the reservation type parameter is subscriptionAndCharge or subscriptionAndReserve and the agreement[type]=unscheduled, the agreement[unscheduled_type] parameter is mandatory.

Possible values:

  • incremental (Notes: No cardholder authentication required)
  • resubmission (Notes: No cardholder authentication required)
  • delayedCharges (Notes: No cardholder authentication required)
  • reauthorisation (Notes: No cardholder authentication required)
  • noShow (Notes: No cardholder authentication required)
  • charge (Notes: Strong Customer Authentication takes place.)
 string No
agreement[expiry] This is the date when the agreement expires. It must have the format YYYYMMDD. The maximum supported values by MobilePay Subscriptions is 18 weeks. string No
agreement[frequency]

It is a integer value representing the frequency between the charge agreement requests made by the merchant. Possible values: 0 - Flexible; 1 - Daily; 7 - Weekly; 14 - Biweekly; 30 - Monthly; 90 - Quarterly; 365 - Yearly.

Values shown in bold above are supported by all payment methods supporting recurring agreements. Klarna is limited to these 4 only.

_

Default Value: Monthly for recurring/instalment. Not allowed for unscheduled agreement.

 integer No.
agreement[next_charge_date] This is the date of the first charge agreement request made by the merchant. It must have the format YYYYMMDD. string No
agreement[admin_url]

This is a link to a page on the merchant side where the customer can manage the agreement.

 string No
agreement[retention_period]

The customer will be able to cancel the agreement only after passing this retention period. The maximum supported value by MobilePay Subscriptions is 24 hours.

 string No

This parameters are not supported when seting up a subscription. You can use these parameters when having the 3DS Adviser feature previously activated by Finaro.

This feature gives customers a more frictionless experience when paying in your shop for transactions flagged with a Low-Risk exemption.

Parameter Description Type Mandatory
authentication[exemption]

This is the exemption type to use when doing the transaction authentication.

Possible values:

  • TRA
 string No
authentication[exemption_mode]

This is the type of the exemption to use when making the transaction authentication.

Possible values:

  • Enabled
  • Enforced

We'll do a direct authorization when Enforced value is provided. Nonetheless, we'll do the authentication in case of a soft decline.

 string  No

For AFT transaction please check on the relevant section below.

Parameter Description Type Mandatory
customer_info[username]

The customer's e-user name or user id. This uniquely identifies the user in your system.

 string

Yes - for Trustly
customer_info[cardholder_name]

The customer's cardholder name.

 string Required for Mobile Wallet (MobilePay/Vipps) to support 3DS fallback
customer_info[organisation_name] The organisation name. string Yes, in case of a business customer.
customer_info[organisation_number] The organisation identifier. string Yes, in case of a business customer.
customer_info[organisation_entity_type] The organisation nature.

ltd - limited company

plc - public limited company

public_institution - public institution

other - all other organisation types

 Yes, in case of a business customer.
customer_info[organisation_vat_id] The organisation VAT identifier. string Yes, in case of a business customer.
customer_info[company_name] Name of the customer, if the customer type is Business string *Deprecated
Please use customer_info[organisation_name] field instead.
customer_info[type] Indicator of whether the customer is an individual or a business private/business *Deprecated
Any customer_info[organisation_*] field set will trigger the business customer indicator.
customer_info[company_type] The nature of the company

ltd - limited company

plc - public limited company

public_institution - public institution

Other - all other company types

 		*Deprecated
Please use customer_info[organisation_entity_type] field instead.
customer_info[vat_id] The company's VAT registration number string *Deprecated
Please use customer_info[organisation_vat_id] field instead.
customer_info[shipping_att] The name of the person receiving the purchase on behalf of the company string Used if the customer_info[type]=business; optional but recommended
customer_info[shipping_lastname]

The last name for the customer's shipping address.

 string
Yes
customer_info[shipping_firstname]

The first name for the customer's shipping address.

 string
Yes
customer_info[shipping_address] The street address of the customer's shipping address.
See the Notes on Addresses in Klarna Payments for more details on handling addresses for KP.
 string
YesFor Norway, you can only ship to a customer's legal address
customer_info[shipping_postal]

The postal code of the customer's shipping address.

 string  
customer_info[shipping_region]

The region of the customer's shipping address.

 string  
customer_info[shipping_country]

The country of the customer's shipping address as a 2 character ISO-3166 country code.

 [a-zA-Z]{2}  
customer_info[shipping_city]

The city of the customer's shipping address.

 string  
customer_info[shipping_ref] A reference that can be used to track the order string Optional. Can be used for B2B transactions (the customer_info[type]=business)
customer_info[email]

The customer's email address. It is required for 3DS to provide a valid email address, which then increases the chances for a frictionless flow, and therefore conversion. If provided will auto-fill the Email input for credit card forms. Please ensure you populate this field to improve the user experience.

string

Yes for all Przelewy24 transactions

Yes for NO and DE
customer_info[customer_phone]

The customer's telephone number, without spaces. This must include the country code. You can prefix the code with + (e.g. +446721846), or 00 (e.g. 00446721846), or omit the prefix (e.g. 446721846).

This value is used to prefill the number on the MobilePay Subscriptions landing page. The customer will have a better experience when setting this parameter.

 		string  
customer_info[birthdate]

The birth date of the customer

Mandatory if your MCC code is 6012.

 Date (yyyy-mm-dd) Yes, if your MCC code is 6012
customer_info[billing_lastname]

The last name for the customer's billing address.

Mandatory if your MCC code is 6012.

 string

Yes, for DK, FI, and DE.

Yes
Yes
Yes
Yes
Yes
customer_info[billing_firstname]

The first name for the customer's billing address.

string

Yes, for DK, FI, and DE

Yes
Yes
Yes
Yes
Yes
customer_info[billing_address]

The street address of the customer's billing address.

See the Notes on Addresses in Klarna Payments for more details on handling addresses for KP.
 string

Yes, for DK, FI, and DE
customer_info[billing_city]

The city of the customer's billing address.

Mandatory for fraud detection.

string  
customer_info[billing_region]

The region of the customer's billing address.

Mandatory for fraud detection.

string  
customer_info[billing_postal]

The postal code of the customer's billing address.

Mandatory if your MCC code is 6012.

Mandatory for fraud detection.

string

Yes

Yes for US transactions.
customer_info[billing_country]

The country of the customer's billing address as a 2 character ISO-3166 country code. Northern Ireland is an exception; see here.

Mandatory for fraud detection.

[a-zA-Z]{2}

Yes
customer_info[billing_att] The name of the person/role who manages the billing for the company string  
customer_info[billing_ref] A reference, for example, cost center, that can be used to track the purchase order string Optional. Can be used for B2B transactions (the customer_info[type]=business)
customer_info[bank_phone]

The phone number of the bank where the credit card was issued.

 string  
customer_info[bank_name]

The name of the bank where the credit card was issued.

 string  
customer_info[gender]

Certain invoice payment providers require gender to be sent. Use this field to comply with that requirement.

If this parameter is required by the provider, but not set in the method call, the customer is asked for this information on the payment page (callback_form).

FMmalefemale Required for Klarna payments in Germany (DE), Netherlands (NL), and Austria (AT) if customer_info[type]=private
customer_info[client_session_id]

A unique identifier of the customers session (eg. an md5 hash of the real session id). Used for fraud detection.

 string  
customer_info[client_accept_language]

The language setting of the customers browser. Used for fraud detection.

 string  
customer_info[client_user_agent]

The customers browser identification. Used for fraud detection.

 string   Required when use wallet flow with mobile app redirect url(callback_mobile_app_redirect)
customer_info[client_forwarded_ip]

The customers IP address as forwarded by transparent proxy. Used for fraud detection.

 string  

AFT specific requirements for customer and recipient parameters. Please check AFT Integration Scenarios for more details.

Recipient information - mandatory

Parameter Description Type Mandatory
recipient_info[username]

The recipient's e-user name or user id. This uniquely identifies the user in your system.

 string
recipient_info[account_identifier]

The recipient's account identifier. It can be a name of customer's account or pan.

 string

Yes
recipient_info[email]

The recipient's email address.

string
recipient_info[customer_phone]

The recipient's telephone number, without spaces. This must include the country code. You can prefix the code with + (e.g. +446721846), or 00 (e.g. 00446721846), or omit the prefix (e.g. 446721846).

 string
recipient_info[birthdate]

The birth date of the recipient.

 Date (yyyy-mm-dd)

Yes
recipient_info[gender]

Gender of the recipient.

 FMmalefemale
recipient_info[billing_lastname]

The last name for the recipient's billing address.

 string

Yes
recipient_info[billing_firstname]

The first name for the recipient's billing address.

string

Yes
recipient_info[billing_address]

The street address of the recipient's billing address.

 string

Yes
recipient_info[billing_city]

The city of the recipient's billing address.

 string

Yes
recipient_info[billing_region]

The region of the recipient's billing address.

 string

string(3) for
CA, US, COL and NIC

Yes, for CA, US, COL and NIC
recipient_info[billing_postal]

The postal code of the recipient's billing address.

 string(6)

Yes
recipient_info[billing_country]

The country of the recipient's billing address as a 2 character ISO-3166 country code. Northern Ireland is an exception; see here.

 [a-zA-Z]{2}

Yes
recipient_info[shipping_lastname]

The last name for the recipient's shipping address.

 string
recipient_info[shipping_firstname]

The first name for the recipient's shipping address.

 string
recipient_info[shipping_address] The street address of the recipient's shipping address. string
recipient_info[shipping_postal]

The postal code of the recipient's shipping address.

 string  
recipient_info[shipping_region]

The region of the recipient's shipping address.

 string  
recipient_info[shipping_country]

The country of the recipient's shipping address as a 2 character ISO-3166 country code.

 [a-zA-Z]{2}  
recipient_info[shipping_city]

The city of the recipient's shipping address.

 string  

Customer information (Sender information) - entire section is optional if recipient and sender of the funds are the same person. If provided the mandatory fields requirements needs to be met.

Parameter Description Type Mandatory
customer_info[username]

The customer's e-user name or user id. This uniquely identifies the user in your system.

 string
customer_info[account_identifier]

The customer's account identifier. It can be name of customer's account or pan.

 string
customer_info[shipping_lastname]

The last name for the customer's shipping address.

 string
Yes
customer_info[shipping_firstname]

The first name for the customer's shipping address.

 string
Yes
customer_info[shipping_address] The street address of the customer's shipping address.
See the Notes on Addresses in Klarna Payments for more details on handling addresses for KP.
 string
YesFor Norway, you can only ship to a customer's legal address
customer_info[shipping_postal]

The postal code of the customer's shipping address.

 string  
customer_info[shipping_region]

The region of the customer's shipping address.

 string  
customer_info[shipping_country]

The country of the customer's shipping address as a 2 character ISO-3166 country code.

 [a-zA-Z]{2}  
customer_info[shipping_city]

The city of the customer's shipping address.

 string  
customer_info[email]

The customer's email address. It is required for 3DS to provide a valid email address, which then increases the chances for a frictionless flow, and therefore conversion. If provided will auto-fill the Email input for credit card forms. Please ensure you populate this field to improve the user experience.

string

Yes for all Przelewy24 transactions

Yes for NO and DE
customer_info[customer_phone]

The customer's telephone number, without spaces. This must include the country code. You can prefix the code with + (e.g. +446721846), or 00 (e.g. 00446721846), or omit the prefix (e.g. 446721846).

This value is used to prefill the number on the MobilePay Subscriptions landing page. The customer will have a better experience when setting this parameter.

 		string  
customer_info[birthdate]

The birth date of the customer

 Date (yyyy-mm-dd)
customer_info[billing_lastname]

The last name for the customer's billing address.

 string

Yes
customer_info[billing_firstname]

The first name for the customer's billing address.

string

Yes
customer_info[billing_address]

The street address of the customer's billing address.

 string

Yes
customer_info[billing_city]

The city of the customer's billing address.

 string

Yes
customer_info[billing_region]

The region of the customer's billing address.

 string

Yes, for US and CA
customer_info[billing_postal]

The postal code of the customer's billing address.

 string
customer_info[billing_country]

The country of the customer's billing address as a 2 character ISO-3166 country code. Northern Ireland is an exception; see here.

 [a-zA-Z]{2}

Yes
customer_info[bank_phone]

The phone number of the bank where the credit card was issued.

 string  
customer_info[bank_name]

The name of the bank where the credit card was issued.

 string  
customer_info[gender]

Certain invoice payment providers require gender to be sent. Use this field to comply with that requirement.

If this parameter is required by the provider, but not set in the method call, the customer is asked for this information on the payment page (callback_form).

FMmalefemale Required for Klarna payments in Germany (DE), Netherlands (NL), and Austria (AT) if customer_info[type]=private
customer_info[client_session_id]

A unique identifier of the customers session (eg. an md5 hash of the real session id). Used for fraud detection.

 string  
customer_info[client_accept_language]

The language setting of the customers browser. Used for fraud detection.

 string  
customer_info[client_user_agent]

The customers browser identification. Used for fraud detection.

 string   Required when use wallet flow with mobile app redirect url(callback_mobile_app_redirect)
customer_info[client_forwarded_ip]

The customers IP address as forwarded by transparent proxy. Used for fraud detection.

 string  
Parameter Description Type Mandatory
orderLines The individual line items of the order. This is mandatory for some providers, and recommended for a good customer experience. Array
Yes

Value

Description

Type

Mandatory

description

Description of an item. This value is going to be used as Plan Description when initiating an agreement on MobilePay Subscriptions.

String (255)

Yes.

itemId

The item identification. This value is going to be used as the Plan when initiating an agreement on MobilePay Subscriptions.

Each itemId must be unique within an order.

String (100)

Yes.

quantity

The quantity of the item. The value must be greater than zero.

It is recommended to use the value 1 when the goodsType parameter is set to subscription_model.

Decimal

Yes.

unitPrice

The unit price, excluding sales tax. The value must be greater than zero.

unitPrice supports up to three decimals, however for most acquirers and currencies two decimals are recommended.

For Klarna only 2 decimals are supported.

It is recommended to use the same value as the one set on the amount parameter or 0 when setting up an unscheduled agreement.

Decimal

Yes.

taxPercent

This is the tax percentage of the unit price.

Send both the taxPercent and taxAmount parameters in the method call. If you provide only one, the other is inferred, and rounding errors may occur. The taxAmount is used for the calculation, and taxPercent is printed on the invoice.

Decimal

No

taxAmount

This is the total tax on an order line, before any discounts are applied. It is recommended to use taxAmount if possible. If you provide both taxPercent and taxAmount, the amount takes precedence.

Send both the taxPercent and taxAmount parameters in the method call. If you provide only one of the taxPercent and taxAmount parameters, the other parameter is inferred, and rounding errors may occur.
The taxAmount is used for the calculation, and taxPercent is printed on the invoice.

Decimal

Yes

unitCode

The relevant measurement unit for the order line. For example, kg.

String (50)

 

discount

The order line's discount in percent. Must be a non-negative decimal number if provided. Will be used to calculate final amount for order line after applying taxes.

Decimal

 
goodsType

The goods type of the order line -

shipment - Covers the cost of shipping
handling - Covers the cost of handling the order
item - Covers the cost of a physical product
digital - Covers the cost of a digital product*
discount - Covers a discount on the order**
gift_card - Covers a gift card**
physical - Covers the cost of a physical product (equivalent to item)*
sales_tax - Covers sales tax on the order**
subscription_model - Special type used to handle subscription setup for some acquirers***

The used value must be subscription_model for setting up subscriptions on MobilePay Subscriptions, see MobilePay Agreements
It is recommended use the first element of the orderLines array for agreement setup: orderLines[0][goodsType] = subscription_model.

* Specific to Klarna and PayPal payments

** Specific to Klarna payments

*** Specific to MobilePay, PayPal and Klarna subscriptions

 String (255)

Yes

imageUrl

The full URL of the icon for the item

String (255)

 
productUrl The full URL for the description of the item String (255)  
Here you have an overview of how the order lines are expected to be received.
  • orderLines[0][itemId]
  • orderLines[0][description]
  • orderLines[0][quantity]
  • orderLines[0][unitPrice]
  • orderLines[1][itemId]
  • orderLines[1][description]
  • ...
  • orderLines[N][quantity]
  • orderLines[N][unitPrice]
N is the number of the order lines you have.

Example order value calculations

Tax as percentage

Let's have an order of one order line with given values:

quantity = 5
unitPrice = 100.00
taxPercent = 17.00
discountPercent = 11.00

Then for this order line we got gross amount:

order_line_amount_with_tax = ( quantity * unitPrice ) + ( quantity * unitPrice ) * taxPercent
order_line_amount_with_tax = ( 100 * 5 ) + ( 100 * 5 ) * 17% = 500 + 85 = 585

gross_order_line_amount = order_line_amount_with_tax - order_line_amount_with_tax * discountPercent
gross_order_line_amount = 585 - 585 * 11.00% = 520.65

and total amount of the order will be:

amount = sum of order lines
amount = 520.65

Tax as amount

Let's have the same order line but with tax represented as amount:

quantity = 5
unitPrice = 100.00
taxAmount = 85.00
discountPercent = 11.00

Then for this order line we got gross amount:

order_line_amount_with_tax = ( quantity * unitPrice ) + taxAmount
order_line_amount_with_tax = 100 * 5 + 85 = 500 + 85 = 585

gross_order_line_amount = order_line_amount_with_tax - order_line_amount_with_tax * discountPercent
gross_order_line_amount = 585 - 585 * 11.00% = 520.65

and total amount of the order will be:

amount = sum of order lines
amount = 520.65

Value

Description

Type

Mandatory

travel[fromDate]

The first date of the trip.

Date String yyyy-MM-dd (ex. 2024-05-29)

Only in certain travel cases.

travel[toDate]

The last date of the trip.

Date String yyyy-MM-dd (ex. 2024-05-29)

Only in certain travel cases.
Parameter Description Type Mandatory
dynamic_descriptor The description that appears on users bank statement. This is normally set on the terminal configuration but is provided here as an API parameter to overwrite the configuration when needed on a per-payment granularity.

It has a unique format of {string(25)}*{string(13)}
The first part of the string should represent the business name separated with a * and then an identifier.
This identifier can be used as template. Valid template inputs are %orderId, %paymentId, %currency.numeric, %currency.alpha, %customer.ip, %customer.email, %customer.phone, %customer.username.

An example payment with orderId=123 by a business Computers&Company could be CompCo*%orderId which would produce CompCo*123 on the customer's bank statement.

Caution: The underlying value of the templated identifier is what counts towards the maximum length of 13 and if it exceeds legal values it will depend on the terminal's dynamic descriptor policy whether it will be passed to the acquirer or not. 		String (39)
No
  • The OK page is not used, because customers have to sign a document after submitting the form.
  • If a payment is initialized, but the customer leaves before the payment is completed, the payment will be in an incomplete state, and the TransactionStatus result is epayment_initialized.
  • The notification page (callback_notification) is always called.
  • The notification page (callback_notification) is, in most cases, triggered before the OK callback (callback:ok).
  • The notification page (callback_notification) is used for chargebacks.
    • The callback pages in use are determined by the relevant credit card acquirer.
  • The payment page (callback_form) is not shown to your customer.
  • For more information about the callback pages in use, see the specifics for each credit card acquirer, Payment methods and providers.
  • The notification page (callback_notification) is used when your customer doesn't return to the browser after a completed payment, and for chargebacks.
  • The open page (callback_open) is used for pending transactions.
  • The notification page (callback_notification) is used for transactions pending clarification.

Parameter

Description

Type

 Mandatory?
config[callback_form] This is the callback form, or the payment page, and corresponds to the Callback url (form) setting in the Terminal settings. For more information, see Settings for the Payment Page (callback_form). For information about custom styling for the payment page, see Styling the payment page (callback_form). String (Url) No
config[callback_ok] This url is called when a payment succeeds, and corresponds to the Callback url (Ok) setting in Terminal settings. For more information, see Settings for the Payment OK page (callback_ok). String (Url) No
config[callback_fail] This url is called when a payment fails, and corresponds to the Callback url (Fail) setting in Terminal settings. For more information, see Settings for the fail page (callback_fail).

As Swish only allows one open payment at a time, the callback_fail form for Swish could offer some explanation, such as "The customer may have an open payment" or "The customer should check their Swish app for open payments".

 String (Url) No
config[callback_open] This url is called when a payment returns with status Open, and corresponds to the Callback url (open) setting in Terminal settings. For more information, see Settings for the open page (callback_open).

For Klarna payments, the open page (callback_open) is used for pending transactions.

 String (Url) No
config[callback_notification] This url is called when a notification is returned after the customer has left the payment flow, and corresponds to the Callback url (notification) setting in Terminal settings. For more information, see Payment Notification (callback_notification)

For Klarna payments, the notification page (callback_notification) is used for transactions pending clarification.

In some cases, the notification page can be called before the ok page or fail pages are called.
 String (Url) No
config[callback_verify_order]

This URL is called just before the payment is processed.

  • To return a value that is not part of the normal POST parameters, you can prepend GET parameters to the URL.
  • To allow the payment to proceed, you must return a HTTP response with code 200, and a HTML/TEXT response with the value "OKAY". Anything else results in an error message, and an aborted/declined transaction.

If the payment fails, the first 255 characters of your response is shown as an error message to the customer.

 String (Url) No
config[callback_redirect]

This url is called whenever the customer is redirected to a third party, and corresponds to the Callback url (redirect) setting in Terminal settings. For more information, see Settings for the redirect page (callback_redirect).

 String (Url) No
config[callback_mobile_app_redirect] This is an APP URL where the customer will be redirected from wallet payment app when a payment fails or succeeds. For more information, see Payment Mobile App Redirect Page (callback_mobile_app_redirect) String (Url) No

The table shows the most pertinent response values for the method. For a complete list of API response parameters, see API Response structure (XML).

Value Description
Result

The result of the request, for example:

  • Success
  • Fail
  • Open
  • Redirect
  • PartialSuccess
  • Error. The MerchantErrorMessage and CardHolderErrorMessage elements show more information about the error.
PaymentRequestId The payment request ID, used for subsequent processing.
Url The URL to redirect your customer to.
DynamicJavascriptUrl A url you can use in a Javascript to create an overlay payement page. For more information, see Styling a floating payment window.
AppUrl Contains a URL you can use to initiate the credit card wallet payment in app. For more information, see Initiate Credit Card Wallet in App.

To fetch the complete cookie, including the session cookie, in php, you can use the following syntax:

$_SERVER['HTTP_COOKIE']

Sample of the XML response using GET

<?xml version="1.0"?>
<APIResponse version="20170228">
	<Header>
		<Date>2010-09-29T12:34:56+02:00</Date>
		<Path>API/createPaymentRequest</Path>
		<ErrorCode>0</ErrorCode>
		<ErrorMessage></ErrorMessage>
	</Header>
	<Body>
		<Result>Success</Result>
		<PaymentRequestId>2349494a-6adf-49f7-8096-2125a969e104</PaymentRequestId>
		<Url>https://gateway.altapaysecure.com/merchant.php/API/requestForm?pid=2349494a-6adf-49f7-8096-2125a969e104</Url>
		<DynamicJavascriptUrl>https://gateway.altapaysecure.com/eCommerce.php/API/embeddedPaymentWindow?pid=2349494a-6adf-49f7-8096-2125a969e104</DynamicJavascriptUrl>
	</Body>
</APIResponse>

When you have redirected your customer to the URL provided by the call to createPaymentRequest, and your customer has successfully finished the payment, this XML is sent to the ok page (callback_ok). For more information, see Settings for the Payment OK page (callback_ok).

<?xml version="1.0"?>
<APIResponse version="20170228">
	<Header>
		<Date>2013-04-30T15:53:40+02:00</Date>
		<Path>API/reservation</Path>
		<ErrorCode>0</ErrorCode>
		<ErrorMessage></ErrorMessage>
	</Header>
	<Body>
		<Result>Success</Result>
		<Transactions>
			<Transaction>
				<TransactionId>7</TransactionId>
				<PaymentId>ccc1479c-37f9-4962-8d2c-662d75117e9d</PaymentId>
				<AuthType>payment</AuthType>
				<CardStatus>InvalidLuhn</CardStatus>
				<CreditCardExpiry>
					<Year>2028</Year>
					<Month>08</Month>
				</CreditCardExpiry>
				<CreditCardToken>c63e01f71c0e7eced288f3a01aa94cce7d43a48f</CreditCardToken>
				<CreditCardMaskedPan>412012****4444</CreditCardMaskedPan>
				<CardInformation>
					<IsTokenized>false</IsTokenized>
					<Token>hYKu5yO33OsWYfT7g4weghvPjBnb3YEZYDysb7NzAf/sHk7j5j5ejzfF2ZyhLyggcCgaNKEmjg==+1</Token>
					<MaskedPan>412012******1111</MaskedPan>
					<Expiry>
						<Year>2028</Year>
						<Month>08</Month>
					</Expiry>
					<IssuingCountry>DK</IssuingCountry>
					<LastFourDigits>1111</LastFourDigits>
					<Scheme>VISA</Scheme>
				</CardInformation>
				<ThreeDSecureResult>Not_Attempted</ThreeDSecureResult>
				<LiableForChargeback>Merchant</LiableForChargeback>
				<CVVCheckResult>Not_Applicable</CVVCheckResult>
				<BlacklistToken>12b14f9aa5fc7630c54ecc30eba0ff563f7671fb</BlacklistToken>
				<ShopOrderId>668850_orderId</ShopOrderId>
				<Shop>AltaPay Functional Test Shop</Shop>
				<Terminal>AltaPay Test Terminal</Terminal>
				<TransactionStatus>preauth</TransactionStatus>
				<ReasonCode>OPEN_WAITING_FOR_ACQUIRER</ReasonCode>
				<MerchantCurrency>978</MerchantCurrency>
				<MerchantCurrencyAlpha>EUR</MerchantCurrencyAlpha>
				<CardHolderCurrency>978</CardHolderCurrency>
				<CardHolderCurrencyAlpha>EUR</CardHolderCurrencyAlpha>
				<ReservedAmount>5.55</ReservedAmount>
				<CapturedAmount>0.00</CapturedAmount>
				<RefundedAmount>0.00</RefundedAmount>
				<RecurringDefaultAmount>0.00</RecurringDefaultAmount>
				<CreatedDate>2013-04-30 15:53:39</CreatedDate>
				<UpdatedDate>2013-04-30 15:53:40</UpdatedDate>
				<PaymentNature>CreditCard</PaymentNature>
				<PaymentSchemeName>Visa</PaymentSchemeName>
				<PaymentNatureService name="TestAcquirer">
					<SupportsRefunds>true</SupportsRefunds>
					<SupportsRelease>true</SupportsRelease>
					<SupportsMultipleCaptures>true</SupportsMultipleCaptures>
					<SupportsMultipleRefunds>true</SupportsMultipleRefunds>
				</PaymentNatureService>
				<FraudRiskScore>5</FraudRiskScore>
				<FraudExplanation>For the test fraud service the risk score is always equal mod 101 of the created
				amount for the payment
				</FraudExplanation>
				<FraudRecommendation>Deny</FraudRecommendation>
			<ChargebackEvents/>
				<PaymentInfos>
					<PaymentInfo name="ka"><![CDATA[v1]]></PaymentInfo>
					<PaymentInfo name="kb"><![CDATA[v2]]></PaymentInfo>
				</PaymentInfos>
			<CustomerInfo/>
			<ReconciliationIdentifiers/>
			</Transaction>
		</Transactions>
	</Body>
</APIResponse>

This example shows a call with only the required parameters, and the corresponding response.

Request

  curl --request POST \
  --url https://<YourShopName>.altapaysecure.com/merchant/API/createPaymentRequest \
  --header 'Authorization: Basic auth' \
  --data terminal='MyTerminal' \
  --data shop_orderid=abc123 \
  --data amount=50 \
  --data currency=EUR \

Response

<APIResponse version="20170228">
	<Header>
		<Date>2017-10-23T11:30:16+02:00</Date>
		<Path>API/createPaymentRequest</Path>
		<ErrorCode>0</ErrorCode>
		<ErrorMessage/>
	</Header>
	<Body>
		<Result>Success</Result>
		<PaymentRequestId>4f81bc4c-3d51-403b-9cc5-118fced75ec5</PaymentRequestId>
		<Url>
			https://testgateway.altapaysecure.com/eCommerce/API/requestForm?pid=4f81bc4c-3d51-403b-9cc5-118fced75ec5
		</Url>
		<DynamicJavascriptUrl>
			https://testgateway.altapaysecure.com/eCommerce/API/embeddedPaymentWindow?pid=4f81bc4c-3d51-403b-9cc5-118fced75ec5
		</DynamicJavascriptUrl>
	</Body>
</APIResponse>

Use the following to test credit card transactions.

If the M character in the credit card number is 1, the 3DSecure v2 method flow will be triggered.

API method Scenario Transaction status Trigger card number

The reservation was initiated and a frictionless flow was triggered.

 TransactionStatus.ACCEPTED
  • Visa: 411100000000051M or 457100000000081M
  • MasterCard: 517000000000001M
  • Example:  4111000000000511

The reservation was initiated and a challenge flow was triggered.

 TransactionStatus.CHALLENGE
  • Visa 411100000000112M or 457100000000062M
  • MasterCard 517000000000992M
  • Example:  4111000000001121

The reservation was initiated and a decoupled challenge flow was triggered.

 TransactionStatus.DECOUPLED
  • Visa: 411100000000013M or 457100000000123M
  • MasterCard:  517000000000553M
  • Example:  4111000000000131

In order to trigger the Authenticated or Rejected result upon authentication, please do so by clicking one of the following buttons in the Mock ACS (testbank):

API method Scenario Type Trigger amount Trigger card number

The payment fails because it is declined by the bank.

 Failed 5.66
  • Pattern: ????????????0566
  • Visa: 4180000000000566
  • MasterCard: 5500000000000566

The payment fails because of a technical error.

Error 5.67
  • Pattern: ????????????0567
  • Visa: 4130000000000567
  • MasterCard: 5590000000000567

The reservation succeeds after a successful 3D Secure verification.

 3DSecureWork 5.68
  • Pattern: ????????????0568
  • Visa: 4170000000000568
  • MasterCard: 5540000000000568

The CVV code is correct.

CVV Check Matched 5.71
  • Pattern: ????????????0571
  • Visa: 4100000000000571
  • MasterCard: 5560000000000571

The CVV code is not correct.

CVV Check MisMatched 5.72
  • Pattern: ????????????0572
  • Visa: 4190000000000572
  • MasterCard: 5510000000000572

The CVV code is not applicable.

CVV Check Not_Applicable 5.73
  • Pattern: ????????????0573
  • Visa: 4140000000000573
  • MasterCard: 5550000000000573

The card verification fails because the card is declined.

Failed 16.66
  • Pattern: ????????????1666
  • Visa: 4120000000001666
  • MasterCard: 5580000000001666

The card verification fails because of a technical error.

Error 16.67
  • Pattern: ????????????1667
  • Visa: 4160000000001667
  • MasterCard: 5530000000001667

Use this test case data to test fraud check responses.

API method Scenario Error type Amount Card Number
Fraud check Accept Accept 101
  • Visa: 4170000000000006
  • MasterCard: 5060000000000006
Fraud check Challenge. Challenge 102
  • Visa: 4170000000000121
  • MasterCard: 5250000000000121
Fraud check Deny. Deny

110
  • Visa: 4170000000000105
  • MasterCard: 5060000000000105
Fraud check Unknown. Unknown Not possible
  • Visa: 4170000000000113
  • MasterCard: 5110000000000113

Use this test case data to test the setup of recurring payments.

API method Scenario Error type Amount Card Number
Setting up a subscription fails because the payment is declined by the bank. Failed 14.66
  • Pattern: ????????????1466
  • Visa: 4130000000001466
  • MasterCard: 5590000000001466
Setting up a subscription fails because of a technical error. Error 14.67
  • Pattern: ????????????1467
  • Visa: 4130000000001467
  • MasterCard: 5590000000001467

Setting up a subscription and creating the first charge succeeds.

Success 13.68
  • Pattern: ????????????1368
  • Visa: 4170000000001368
  • MasterCard: 5540000000001368
Setting up a subscription works, but the first charge fails. Failed 13.69
  • Pattern: ????????????1369
  • Visa: 4120000000001369
  • MasterCard: 5580000000001369
Scenario Error type Amount Card Number
Fails at credit or createPaymentRequest with the appropriate type set. Failed 9.66
  • Pattern: ????????????0966
  • Visa: 4160000000000966
  • MasterCard: 5530000000000966
Fails at credit or createPaymentRequest with the appropriate type set. Error 9.67
  • Pattern: ????????????0967
  • Visa: 4110000000000967
  • MasterCard: 5570000000000967

After you have redirected your customer to the Url, and the customer has completed the payment, a response is sent to the relevant callback page

If a payment was reserved, you can

If a payment was reserved and captured, you can: