2.1. Swift wire transfer

2.1.1. Swift transfer API

To start Swift transaction use Payment form to get receipt-id in order status. https://gate.apropay.com/paynet/api/v2/preauth-form/ENDPOINTID

For integration purposes use staging environment sandbox.apropay.com instead of production gate.apropay.com

Customer -> Merchant: Checkout activate Merchant Merchant -> "Apropay": preauth-form/ENDPOINTID activate "Apropay" "Apropay" --> Merchant: status=processing deactivate "Apropay" deactivate Merchant Merchant -> "Apropay": status/ENDPOINTID activate "Apropay" "Apropay" --> Merchant: status=approved,receipt-id=ae524c7c-be87-11e4-8dfc-aa07a5b093db deactivate "Apropay" alt xml Merchant -> "Apropay": view-invoice-xml/ENDPOINTID/ae524c7c-be87-11e4-8dfc-aa07a5b093db activate "Apropay" "Apropay" --> Merchant: XML deactivate "Apropay" else pdf Merchant -> "Apropay": view-invoice/ENDPOINTID/ae524c7c-be87-11e4-8dfc-aa07a5b093db activate "Apropay" "Apropay" --> Merchant: PDF deactivate "Apropay" end

Payment Form Request Parameters

Note

Request must have content-type=application/x-www-form-urlencoded and Authorization headers.
Acquirer can redefine the necessity of some fields so they become mandatory instead of optional.
Leading and trailing whitespace in input parameters will be omitted.
Request parameter name Length/Type Comment Necessity*
client_orderid 128/String Merchant order identifier. Mandatory
order_desc 64k/String Brief order description Mandatory
first_name 50/String Customer’s first name Optional
last_name 50/String Customer’s last name Optional
ssn 32/Numeric Last four digits of the customer’s social security number. Optional
birthday 8/Numeric Customer’s date of birth, in the format YYYYMMDD. Optional
address1 50/String Customer’s address line 1. Mandatory
city 50/String Customer’s city. Mandatory
state 2/String Customer’s state (two-letter state code). Please see Reference for a list of valid state codes. Mandatory for USA, Canada and Australia. Conditional
zip_code 10/String Customer’s ZIP code Mandatory
country 2/String Customer’s country(two-letter country code). Please see Reference for a list of valid country codes. Mandatory
phone 15/String Customer’s full international phone number, including country code. Optional
cell_phone 15/String Customer’s full international cell phone number, including country code. Optional
email 50/String Customer’s email address. Mandatory
amount 10/Numeric Amount to be charged. The amount has to be specified in the highest units with . delimiter. 10.5 for USD means 10 US Dollars and 50 Cents Mandatory
currency 3/String Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar EUR for European Euro Mandatory
ipaddress 45/String Customer’s IP address, included for fraud screening purposes. Mandatory
site_url 128/String URL the original sale is made from. Optional
control 40/String Checksum generated by SHA-1. See Request authorization through control parameter for more details. Mandatory
redirect_url 128/String URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. You should not use this parameter to retrieve results from Apropay gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Mandatory if both redirect_success_url and redirect_fail_url are missing
redirect_success_url 1024/String URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is approved. You should not use this parameter to retrieve results from Apropay gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Mandatory if redirect_url parameter is missing
redirect_fail_url 1024/String URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is declined or filtered. You should not use this parameter to retrieve results from Apropay gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Mandatory if redirect_url parameter is missing
server_callback_url 128/String URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. See more details at Merchant Callbacks Optional

Payment Form Response

Note

Response has Content-Type: text/html;charset=utf-8 header. All parameters in response are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value
Response parameter name Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
status Status List for details.
paynet-order-id Order id assigned to the order by Apropay
merchant-order-id Merchant order id
serial-number Unique number assigned by Apropay server to particular request from the Merchant.
error-message If status is declined or error this parameter contains the reason for decline or error details
error-code The error code is case of declined or error status
redirect_url The URL to the page where the Merchant should redirect the client’s browser. Merchant should send HTTP 302 redirect, see General Payment Form Process Flow

Swift invoice URL

To get Swift notification in XML use URL https://gate.apropay.com/paynet/view-invoice-xml/ENDPOINTID/RECEIPTID

To get Swift notification in PDF use URL https://gate.apropay.com/paynet/view-invoice/ENDPOINTID/RECEIPTID

Request authorization and debug

Requests to Invoice API use OAuth 1.0a authorization with HMAC-SHA1 signature.
oAuth libraries may be helpful to speed up the integration process.
Key:
HMAC key value is the concatenation of consumer secret (Merchant control key) + & + token secret (empty string).
For example, it will look as follows:
F9F65098-1111-1111-1111-621611111111&
Request body and data string to sign:
Parameters in request body must be arranged in lexicographical order.
Unique random nonce and current timestamp are generated by merchant.
OAuth parameters must be included in request body (oauth_consumer_key, oauth_nonce, oauth_signature_method, oauth_timestamp, oauth_version).
Whole request is used as data string to calculate HMAC-SHA1 signature.
URL and parameters in data string must be percent-encoded and have the following structure:
GET&URL&parameters
Headers and signature:
Authorization header must start from Authorization: OAuth, have oauth_signature and the same OAuth parameters and values as were included in request body (oauth_consumer_key, oauth_nonce, oauth_signature_method, oauth_timestamp, oauth_version).
Merchant login is used as oauth_consumer_key in data string and authorization header, but it is not used as a part of the signing HMAC key.
HMAC-SHA1 signature in binary format must be Base64 and percent-encoded. The signature is sent in request header named ‘Authorization’.
For example, it will look as follows:
9bSeUoR5yJSSJ4KPhotT%2BofEHSQ%3D
Authorization header example:
OAuth realm="",
oauth_version="1.0",
oauth_signature_method="HMAC-SHA1",
oauth_consumer_key="merchantlogin",
oauth_timestamp="1513785920",
oauth_nonce="EqINVv5rkhx",
oauth_signature="9bSeUoR5yJSSJ4KPhotT%2BofEHSQ%3D"

To reproduce your API call, input all of the data from your original request, including the authentication tokens. Don’t forget to set the nonce and timestamp to the values you used. An OAuth signed URL should match regardless of the generating library. If the signatures differ, you know there is a bug in your OAuth signature code.

HTTP method
endpointId
receiptId
version
consumer key
consumer secret
timestamp
nonce
signature method

normalized parameters
signature base string
signature
authorization header
Curl

2.1.2. Extended Swift wire transfer flow

Swift wire transfers handling may be done manually on user interface, using batch upload or via API integration. The following transaction statuses may be available for better control of Swift transfer transactions (please ask your support manager for details):

Stage name Description
AUTH_STARTING Transaction was initiated
AUTH_INVOICED Invoice was issued for the customer. It may be downloaded in back-office, sent to customer by e-mail or requested via API.
AUTH_SENT Customer informed the merchant that invoice have been paid. This stage may be skipped.
CANCEL_APPROVED Customer didn’t complete the transfer. This stage is optional and may be used for better transaction control in back-office.
AUTH_APPROVED Transfer was received by the bank.
CAPTURE_APPROVED Funds were transferred to the merchant’s account (settled).
VOID_APPROVED Funds were returned by the customer (recalled).
REVERSAL_APPROVED Funds were returned to the customer by merchant.
CHARGEBACK_APPROVED Funds were charged back by the customer.