-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Showing
1 changed file
with
295 additions
and
0 deletions.
There are no files selected for viewing
295 changes: 295 additions & 0 deletions
295
content/index/payment-methods/applepay/ppv2/03-01-04-10-applepay.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,296 @@ | ||
|
|
||
| [#Apple Pay] | ||
| == Payment Page | ||
|
|
||
| ==== | ||
| {payment-page-v1} image:images/icons/legacy.png[LEGACY, 80, 20, role="no-zoom", title="Development of this product is discontinued."] is no longer supported. We recommend using {payment-page-v2} integration instead. If you have questions about your existing {payment-page-v1} integration, consult our <<Apple Pay, REST API>> integration guide. | ||
| ==== | ||
|
|
||
| [#PPv2_ApplePay_General] | ||
| === General Information | ||
|
|
||
| This is a reference page for _Apple Pay_. Here you find all the information | ||
| necessary for integrating this payment method into your Hosted and Embedded Payment Page. | ||
|
|
||
| .Are you unfamiliar with the {payment-page-v2} ({GPP})? | ||
|
|
||
| NOTE: Visit one of the integration guides | ||
| (<<PaymentPageSolutions_PPv2_HPP_Integration, Hosted>>, | ||
| <<PaymentPageSolutions_PPv2_EPP_Integration, Embedded>>) for a quick explanation and | ||
| a step-by-step guide before continuing. | ||
|
|
||
| All <<PPv2, {payment-page-v2-abbr}>> integrations share a | ||
| <<PPSolutions_PPv2_Workflow, common process flow>> for creating payments. | ||
|
|
||
| Below, you find example requests for the available transaction type | ||
| <<PPv2_ApplePay_TransactionType_purchase, _purchase_>>, | ||
| including field lists with short descriptions. | ||
|
|
||
| These requests are designed for the testing environment and do not | ||
| use real information. | ||
|
|
||
| NOTE: For production, you need to use production credentials. For details | ||
| contact <<ContactUs, merchant support>>. | ||
|
|
||
| Due to limitations in the Test environment, success responses are not possible. It is recommended that you do a full series of testing in the Production environment before making Apple Pay available to all customers. | ||
|
|
||
| For more details on the ``redirect-url``, see the | ||
| <<PPSolutions_PPv2_ConfigureRedirects, Configuring Redirects and IPNs for {payment-page-v2-abbr}>> | ||
| section. | ||
|
|
||
| For response verification examples, see | ||
| the <<PPSolutions_PPv2_PPv2Security, {payment-page-v2-abbr} Security>> section. | ||
|
|
||
|
|
||
| [#PPv2_ApplePay_About] | ||
| === About Apple Pay | ||
|
|
||
| Apple Pay is an alternative payment method in Poland that allows users to make instant payments and withdraw cash using only the user's standard mobile banking app. | ||
| Transactions are uniquely identified by a 6-digit one-time code, valid for 2 minutes, which the user generates and authenticates in their mobile banking app | ||
|
|
||
|
|
||
| [#PPv2_ApplePay_TestCredentials] | ||
| === Test Credentials | ||
|
|
||
|
|
||
| [cols="35h,65"] | ||
| |=== | ||
| | URI (Endpoint) | ``\https://{pp-test-instance-hostname}/api/payment/register`` | ||
| | Merchant Account ID (MAID) | 5f53e57f-6160-49e3-9996-306d02c56c1f | ||
| | Username | 515225-GetnetEuropeTEST | ||
| | Password | 4cHLRE-Q7YcAP | ||
| | Secret Key (used for response verification) | 285fe5af-09f0-4e99-b8a8-439f14d75e20 | ||
| |=== | ||
|
|
||
| [NOTE] | ||
| ==== | ||
| *Apple Pay in Test Environment* | ||
| When testing Apple Pay, you must follow Apple's instructions on | ||
| ==== | ||
|
|
||
| image::images/03-01-04-09-blik/blik_Demoshop.PNG[blik Demoshop] | ||
|
|
||
|
|
||
| [#PPv2_blik_TransactionType_debit] | ||
| === Transaction Type _debit_ | ||
|
|
||
| A _debit_ transaction charges the specified amount from the account | ||
| holder's bank account and marks it for immediate transfer. | ||
|
|
||
| For a successful _debit_ transaction: | ||
|
|
||
| . Create a payment session (initial request). | ||
| . Redirect the consumer to the payment page (initial response URL). | ||
| . Highly recommended: Parse and process the payment response. | ||
|
|
||
| //- | ||
|
|
||
| We provide ready-made JSON examples for each step of this process. You | ||
| find them below. | ||
|
|
||
| <<PPv2_blik_TestCredentials, Endpoint>> for _blik_ transactions. | ||
|
|
||
| .Initial Request | ||
|
|
||
| The initial request creates the payment session. If it is | ||
| successful, you receive a URL as a response which redirects to the payment form. | ||
|
|
||
| .Request Headers | ||
| [cols="20h,80"] | ||
| |=== | ||
| | Authorization | Basic MTYzOTAtdGVzdGluZzozITMwMTM9RDNmRDhYNw== | ||
| | Content-Type | application/json | ||
| |=== | ||
|
|
||
|
|
||
| .1. Create a Payment Session (Initial Request) | ||
|
|
||
| [source,json,subs=attributes+] | ||
| ---- | ||
| include::{root}/samples/json/WPP_blik_TransactionTypeDebit_1CreateAPaymentSessionInitialRequest.json[] | ||
| ---- | ||
|
|
||
|
|
||
| [cols="15e,10,10,10,5,50"] | ||
| |=== | ||
| 2+| Field (JSON) | Data Type | Mandatory/Optional | Size | Description | ||
|
|
||
|
|
||
| | merchant-account-id e| value | String | Mandatory | 36 | A unique identifier assigned to every merchant account (by {payment-provider-name}). | ||
| 2+| request-id | String | Mandatory | 150 | A unique identifier assigned to every request (by merchant). Used when | ||
| searching for or referencing it later. ``{{$guid}}`` serves as a | ||
| placeholder for a random ``request-id``. | ||
| 2+| order-number | String | Mandatory | 64 | This is the order number of the merchant. If provided, it is displayed on the _blik_ | ||
| landing page as "Order Information". | ||
| 2+| transaction-type | String | Mandatory | 30 | The requested transaction type. For _blik_ payments, the | ||
| transaction-type must be set to ``debit``. | ||
| .2+| requested-amount e| value | Numeric | Mandatory | 18 | The full amount that is requested/contested in a transaction. 2 decimal | ||
| places allowed. | ||
| | currency | String | Mandatory | 3 | The currency of the requested/contested transaction amount. For _blik_ | ||
| payments, the currency must be set to ``PLN``. | ||
| .3+| account-holder e| first-name | String | Optional | 32 | The first name of the account holder. | ||
| | last-name | String | Mandatory | 32 | The last name of the account holder. | ||
| | email | String | Mandatory | 64 | The email address of the account holder. | ||
| | payment-method e| name | String | Mandatory | 15 | The name of the payment method used. Set this value to ``blik``. | ||
| 2+| country | String | Optional | 3 | The country ID of the account holder. It must be set to ``PL``; if it is not provided, | ||
| it will automatically be set to ``PL``. | ||
| 2+| locale | String | Optional | 6 a| With this field you can specify the language in which the _blik_ landing page is displayed. | ||
|
|
||
| Possible values: | ||
|
|
||
| - ``pl`` | ||
| - ``en`` | ||
| - ``de`` | ||
| - ``es`` | ||
| - ``it`` | ||
|
|
||
| //- | ||
|
|
||
| 2+| notification-url | String | Optional | 256 | The URL with which the merchant is notified about the transaction outcome. | ||
| 2+| descriptor | String | Optional | 64 | Describes the transaction. It is shown on the account holder's statement | ||
| along with the blik-Transaction-ID. See section <<blik_BankingStatement, Banking Statement>> for details on the blik-Transaction-ID. | ||
|
|
||
| Length and allowed characters depend on the respective consumer's bank | ||
| system and can vary. | ||
| 2+| success-redirect-url | String | Optional | 256 a| The URL to which the consumer is redirected after successful payment, | ||
| e.g. ``\https://{pp-redirect-url-success}`` | ||
| 2+| fail-redirect-url | String | Optional | 256 a| The URL to which the consumer is redirected after a unsuccessful payment, | ||
| e.g. ``\https://{pp-redirect-url-error}`` | ||
| 2+| cancel-redirect-url | String | Optional | 256 a| The URL to which the consumer is redirected after having canceled payment, | ||
| e.g. ``\https://{pp-redirect-url-cancel}`` | ||
| |=== | ||
|
|
||
|
|
||
| .2. Redirect the Consumer to the Payment Page (Initial Response URL) | ||
|
|
||
| [source,json,subs=attributes+] | ||
| ---- | ||
| include::{root}/samples/json/WPP_blik_TransactionTypeDebit_2RtCttPPIRU.json[] | ||
| ---- | ||
|
|
||
| [cols="15e,10,75"] | ||
| |=== | ||
| | Field (JSON) | Data Type | Description | ||
|
|
||
| | payment-redirect-url | String | The URL which redirects to the payment | ||
| form. Sent as a response to the initial request. | ||
| |=== | ||
|
|
||
|
|
||
| At this point, you need to redirect your consumer to | ||
| ``payment-redirect-url`` (or render it in an _iframe_ depending on your | ||
| <<PPv2, integration method>>). | ||
|
|
||
| Consumers are redirected to the payment form. There they enter their | ||
| data and submit the form to confirm the payment. A payment can be: | ||
|
|
||
| - successful (``transaction-state: success``), | ||
| - failed (``transaction-state: failed``), | ||
| - canceled. The consumer canceled the payment before/after submission | ||
| (``transaction-state: failed``). | ||
|
|
||
| //- | ||
|
|
||
| The transaction result is the value of ``transaction-state`` in the | ||
| payment response. More details (including the status code) can also be | ||
| found in the payment response in the ``statuses`` object. Canceled | ||
| payments are returned as _failed_, but the | ||
| ``status description`` indicates it was canceled. | ||
|
|
||
| In any case (unless the consumer cancels the transaction on a 3rd party | ||
| provider page), a base64-encoded response containing payment information | ||
| is sent to the configured redirection URL. See | ||
| <<PPSolutions_PPv2_ConfigureRedirects, Configuring Redirects and IPNs for {payment-page-v2-abbr}>> | ||
| for more details on redirection targets after payment and transaction status | ||
| notifications. | ||
|
|
||
| You can find a decoded payment response example below. | ||
|
|
||
|
|
||
| .3. Parse and Process the Payment Response (Decoded Payment Response) | ||
|
|
||
| [source,json,subs=attributes+] | ||
| ---- | ||
| include::{root}/samples/json/WPP_blik_TransactionTypeDebit_3ParseAndProcessThePaymentResponseDecodedPaymentResponse.json[] | ||
| ---- | ||
|
|
||
| [cols="15e,10,10,65"] | ||
| |=== | ||
| 2+| Field (JSON) | Data Type | Description | ||
|
|
||
| 2+| notification-url | String | The URL with which the merchant is notified about the transaction outcome. | ||
| 2+| locale | String a| With this field you can specify the language in which the _blik_ landing page is displayed. | ||
|
|
||
| Possible values: | ||
|
|
||
| - ``pl`` | ||
| - ``en`` | ||
| - ``de`` | ||
| - ``es`` | ||
| - ``it`` | ||
|
|
||
| //- | ||
|
|
||
| 2+| parent-transaction-id | String | The ID of the transaction being referenced as a parent. As a | ||
| _debit_ transaction is internally split into sub-transactions, the ``parent-transaction-id`` serves | ||
| to link these sub-transactions. | ||
| .3+| status e| description | String | The description of the transaction status message. | ||
| | severity | String a| The definition of the status message. | ||
|
|
||
| Possible values: | ||
|
|
||
| - ``information`` | ||
| - ``warning`` | ||
| - ``error`` | ||
|
|
||
| //- | ||
| | code | String | Status code of the status message. | ||
| 2+| cancel-redirect-url | String | The URL to which the consumer is redirected after having canceled a | ||
| payment, e.g. ``\https://{pp-redirect-url-cancel}`` | ||
| 2+| success-redirect-url | String | The URL to which the consumer is redirected after successful payment, | ||
| e.g. ``\https://{pp-redirect-url-success}`` | ||
| 2+| fail-redirect-url | String | The URL to which the consumer is redirected after a failed payment, | ||
| e.g. ``\https://{pp-redirect-url-error}`` | ||
| .3+| account-holder e| first-name | String | The first name of the account holder. | ||
| | last-name | String | The last name of the account holder. | ||
| | email | String | The email address of the account holder. | ||
| 2+| request-id | String | A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later. | ||
| 2+| transaction-id | String | A unique identifier assigned to every transaction. Used when searching for or referencing it later. | ||
| 2+| completion-time-stamp | YYYY-MM-DD-Thh:mm:ss | The UTC/ISO time-stamp documents the time and date when the transaction | ||
| was executed. + | ||
|
|
||
| Format: YYYY-MM-DDThh:mm:ss (ISO). | ||
| .2+| requested-amount e| currency | String | The currency of the requested/contested transaction amount. | ||
| | value | Numeric | The full amount that is requested/contested in a transaction. | ||
| | merchant-account-id e| value | String | A unique identifier assigned to every merchant account (by {payment-provider-name}). | ||
| You receive a unique merchant account ID for each payment method. | ||
| 2+| transaction-state | String a| The current transaction state. | ||
|
|
||
| Possible values: | ||
|
|
||
| - ``in-progress`` | ||
| - ``success`` | ||
| - ``failed`` | ||
|
|
||
| //- | ||
|
|
||
| Typically, a transaction starts with state _in-progress_ and finishes | ||
| with state either _success_ or _failed_. This information is returned in | ||
| the response only. | ||
| 2+| transaction-type | String | The requested transaction type. Must be ``debit`` for _blik_ payments. | ||
| | payment-method e| name | String | The name of the payment method used. | ||
| 2+| order-number | String | This is the order number of the merchant. If provided, it is displayed on the _blik_ | ||
| landing page as "Order Information". | ||
| 2+| api-id | String | Identifier of the currently used API. | ||
| 2+| descriptor | String | Describes the transaction. It is shown on the account holder's statement | ||
| along with the blik-Transaction-ID. See section <<blik_BankingStatement, Banking Statement>> for details | ||
| on the blik-Transaction-ID. | ||
|
|
||
| Length and allowed characters depend on the respective consumer's bank | ||
| system and can vary. | ||
| 2+| country | String | The country ID of the account holder. It must be ``PL``; if it is not | ||
| provided, it will be automatically set to ``PL``. | ||
| |=== | ||
|
|