====== Accepting Bank Transfer Payments ====== ~~TOC~~ %CompanyName-hosted payment page enables you to create secure and fully customized payment forms that let you accept bank transfer payments on your website. This solution works across devices and doesn't require much development work, all you need to do is send us a ''POST'' request with a set of pre-defined fields. ^ **TYPE** ^ **SANDBOX URL** ^ | Payment | ''%URLTestPayments'' | ===== Request ===== ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ | TERMINALID | Y | ^{string ''[ 1 .. 50 ] characters''} \\ The terminal number assigned by %CompanyName. | | ORDERID | Y | ^{string ''[ 1 .. 24 ] characters''} \\ A unique identifier for the order assigned by the merchant. | | CURRENCY \\ | Y | ^{string ''3-char ISO 4217 code''} \\ The currency of the bank transfer. | | AMOUNT | Y | ^{number ''> 0''} \\ The total amount to be authorized. | | DATETIME | Y | ^{string ''DD-MM-YYYY:HH:MM:SS:SSS''} \\ The transaction date and time. | | HASH \\ ^{See notes: [[hpp_payment_features#ND001 - Hash generation|ND001]]} | Y | ^{string ''[ 1 .. 128 ] characters''} \\ A HASH code formed by part of the request fields. | | ACCOUNTHOLDER_NAME | N | ^{string ''[ 1 .. 50 ] characters''} \\ Client's bank account name . If provided, it will be used to pre-populate the account holder name field on the payment page. | | DESCRIPTION | N | ^{string ''[ 1 .. 1024 ] characters''} \\ A brief description of the transaction. | | EMAIL \\ ^{See notes: [[hpp_bank_transfer#ND004 - Cardholder email field|ND004]]} | N | ^{string ''[ 1 .. 128 ] characters''} \\ The cardholder email address. \\ If **Email Cardholder Receipt** feature is enabled on the terminal, we will use this address to delivery transaction receipts to your customer. | | RECEIPTPAGEURL | N | ^string \\ This is the webhook that %CompanyName will use to send you the result of the transactions. If provided, this will override the terminal setting in the Selfcare System. | | ADDRESS1 \\ | N | ^{string ''[ 1 .. 50 ] characters''} \\ The first line of the billing address. | | ADDRESS2 | N | ^{string ''[ 1 .. 50 ] characters''} \\ The second line of the billing address. | | POSTCODE \\ | N | ^{string ''[ 1 .. 50 ] characters''} \\ The postal code of the billing address. | | CITY \\ | N | ^{string ''[ 1 .. 128 ] characters''} \\ The city of the billing address. | | REGION \\ | N | ^{string ''[ 1 .. 128 ] characters''} \\ The region of the billing address. | | COUNTRY \\ | N | ^{string ''2-char ISO 3166-1 code''} \\ The country of the billing address. | | PHONE | N | ^{string ''[ 5 .. 20 ] characters''} \\ The cardholder phone number. International numeric format. | | CUSTOMFIELD | N | You can send any of the custom fields configured on your terminal. Otherwise, they will be displayed as inputs, so that the cardholder can populate them. All custom fields will be stored along with the transaction details and echoed back to the Receipt URL. Check **[[selfcare:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** for more details. | | PAYMENTOPTIONS | N | ^string \\ ''CARD'' \\ ''BANK_TRANSFER'' \\ ''CARD_AND_BANK_TRANSFER'' \\ Restricts payment options to either cards, bank transfer providers or both. Not providing a value is equivalent to the ''CARD_AND_BANK_TRANSFER'' option. | | OTHERFIELD | N | Any other fields sent in the request will be treated as metadata. They are not going to be stored, but they'll be echoed back to the Receipt URL. Note that this is subject to the max length of a HTTP GET request which we would conservatively recommend considering to be 2000 characters. | | CARDREFERENCE | N | ^{string ''[ 12 .. 19 ] characters''} \\ Token reference of an existing Secure Token.\\ If provided, your customer won't be able to change the account details or use a different payment method on the hosted page. | ==== Request notes ==== ==ND001 - Hash generation== See how to generate a hash string at **[[selfcare:api_specification:special_fields_and_parameters|Special Fields and Parameters]]**. For this specific feature, you should use one of the following formats: TERMINALID:ORDERID:AMOUNT:DATETIME:RECEIPTPAGEURL:SECRET \\ ==ND002 - Hosted page in an iFrame== If you don't want the customer to leave your site you can implement the HPP within an iframe. There are two ways to do that: - Build and submit the form as with standard integration, but within the iFrame. - Build the POST query string within the main page and then create an iFrame with the string as it's SRC value. Either way, the following extra parameter should also be included in the request: ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ | INIFRAME | Y | ''Y'' - Ensures that all redirects performed by our system do not break out of the iFrame. | \\ ==ND003 - Storing account details== Give customers the option to store their account details during a payment. To display this option, you just need to include the field below in the request: ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ | SECURECARDMERCHANTREF | Y | ^{string ''[ 1 .. 200 ] characters''} \\ Unique Reference assigned by the merchant to identify the stored account details. | {/gateway} \\ ==ND004 - Cardholder email field== This field is available for all terminals, but depending on the **Hosted payment page email field setup** terminal setting, it might have one of the following behaviors: * **Hidden** - the gateway accepts the field, if sent, and adds it to the transaction, but does not show it to the customer. * **Optional** - an optional e-mail field is displayed to the cardholder. If you send the ''EMAIL'' parameter in the request, we'll use its value to pre-populate the field. * **Mandatory** - a required e-mail field is displayed to the cardholder. If you send the ''EMAIL'' parameter in the request, we'll use its value to pre-populate the field. ==== Request sample ==== * **Scenario**: Minimum request containing only mandatory data. * **Terminal Secret**: x4n35c32RT.

\\ ===== Response ===== Assuming valid details were sent, the hosted page will be displayed to the cardholder and he'll be prompted to enter his card details. Once the payment is processed, the following parameters will be forwarded to the **Receipt URL** configured in your terminal: ^ **FIELD** ^ **DESCRIPTION** ^ | ORDERID | ^{string ''[ 1 .. 24 ] characters''} \\ Echoed back from the request. | | UNIQUEREF | ^{string ''[ 10 ] characters''} \\ Unique reference assigned by the gateway that identifies the transaction on both platforms. **Note:** Clients must be able to store this value in order to eventually perform follow up operation on existing transactions. | | TRANSIT_NUMBER | ^{string ''[ 5 ] characters''} \\ Client's bank branch/transit number. | | ROUTING_NUMBER | ^{string ''[ 9 ] characters''} \\ The 9-digit ABA routing transit number of the account. | | ACCOUNT_NUMBER | ^string \\ Client's bank account number masked with the character ''*'' except last four digits. | | INSTITUTION_NUMBER | ^{string ''[ 3 ] characters''} \\ Client's institution number. | | ACCOUNT_TYPE | ^string \\ ''CHECKING'' \\ ''SAVINGS'' \\ The account type of the client's bank account. | | RESPONSECODE | ^string \\ ''A'': Approval \\ ''D'': Declined \\ | | RESPONSETEXT | ^{string ''[ 0 .. 48 ] characters''} \\ A brief description sent by the processor about the transaction result. | | DISCOUNT_AMOUNT | ^{number ''> 0''} \\ The discount amount. | | DATETIME | ^{string ''DD-MM-YYYY:HH:MM:SS:SSS''} \\ The processing date and time of the transaction. | | EMAIL | ^{string ''[ 1 .. 128 ] characters''} \\ Echoed back from the request.| | PHONE | ^{string ''[ 5 .. 20 ] characters''} \\ Echoed back from the request. | | COUNTRY | ^{string ''2-char ISO 3166-1 code''} \\ Echoed back from the request. | | HASH \\ ^{See notes: [[hpp_payment_features#ND001 - Hash validation|ND001]]} | ^{string ''[ 1 .. 128 ] characters''} \\ A HASH code formed by part of the response fields. | | CUSTOMFIELD | Echoed back from the request. | \\ ==== Response notes ==== ==ND001 - Hash validation== A hash string is also included in the response, so that you can implement a verification logic to make sure it was sent by %CompanyName. See how to decode and validate a hash string at **[[selfcare:api_specification:special_fields_and_parameters|Special Fields and Parameters]]**. For this specific feature, you should expect one of the following formats: /** * The general case */ TERMINALID:ORDERID:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET \\ ==ND002 - Secure Token registration== By including the SECURECARDMERCHANTREF field in the request, you give customers the option to store their account details. \\ If a customer checks that option, the gateway automatically triggers a secure registration and adds the following extra parameters to the response: ^ **FIELD** ^ **DESCRIPTION** ^ | ISSTORED | ^boolean \\ ''true'', ''false'' | | SCERROR | If ''ISSTORED = false'', check out this field for a brief description of the failure. | | MERCHANTREF | ^{string ''[ 1 .. 200 ] characters''} \\ The same ''SECURECARDMERCHANTREF'' you sent in the request. | \\