diff --git a/_includes/payment-order-3-1.md b/_includes/payment-order-3-1.md new file mode 100644 index 0000000000..6a1bafcdbb --- /dev/null +++ b/_includes/payment-order-3-1.md @@ -0,0 +1,220 @@ +{% capture documentation_section %}{%- include utils/documentation-section.md -%}{% endcapture %} +{% assign operation_status_bool = include.operation_status_bool | default: "false" %} +{% assign features_url = documentation_section | prepend: '/' | append: '/features' %} + +## Payment Order Request + +{:.code-view-header} +**Request** + +```http +POST /psp/paymentorders HTTP/1.1 +Host: {{ page.api_host }} +Authorization: Bearer +Content-Type: application/json;version=3.1 + +{ + "paymentorder": { + "operation": "Purchase", + "currency": "SEK", + "amount": 1500, + "vatAmount": 375, + "description": "Test Purchase", + "userAgent": "Mozilla/5.0...", + "language": "sv-SE", + "instrument": false, + "implementation": "PaymentsOnly", + "urls": { + "hostUrls": [ "https://example.com", "https://example.net" ], //Seamless View only + "paymentUrl": "https://example.com/perform-payment", + "completeUrl": "https://example.com/payment-completed", + "cancelUrl": "https://example.com/payment-cancelled", + "callbackUrl": "https://api.example.com/payment-callback", + "logoUrl": "https://example.com/logo.png" //Redirect only + }, + "payeeInfo": { + "payeeId": "{{ page.merchant_id }}", + "payeeReference": "AB832", + "payeeName": "Merchant1", + "orderReference": "or-123456" + } + } +} +``` + +{% capture table %} +{:.table .table-striped .mb-5} +| Required | Field | Type | Description | +| :--------------: | :--------------------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| {% icon check %} | {% f paymentOrder, 0 %} | `object` | The payment order object. | +| {% icon check %} | {% f operation %} | `string` | {% include fields/operation.md %} | +| {% icon check %} | {% f currency %} | `string` | The currency of the payment. | +| {% icon check %} | {% f amount %} | `integer` | {% include fields/amount.md %} | +| {% icon check %} | {% f vatAmount %} | `integer` | {% include fields/vat-amount.md %} | +| {% icon check %} | {% f description %} | `string` | The description of the payment order. | +| {% icon check %} | {% f userAgent %} | `string` | {% include fields/user-agent.md %} | +| {% icon check %} | {% f language %} | `string` | The language of the payer. | +| | {% f instrument %} | `string` | Only used for [Instrument Mode][instrument-mode]. Set the field to the payment instrument you wish to display. If no instrument is specified, the full payment menu will be displayed. | +| | {% f implementation %} | `string` | Indicates which implementation to use. | +| {% icon check %} | {% f urls %} | `object` | The `urls` object, containing the URLs relevant for the payment order. | +| {% icon check %} | {% f hostUrls, 2 %} | `array` | The array of URLs valid for embedding of Swedbank Pay Seamless Views. | +| | {% f paymentUrl, 2 %} | `string` | {% include fields/payment-url.md %} | +| {% icon check %} | {% f completeUrl, 2 %} | `string` | {% include fields/complete-url.md %} | +| {% icon check %} | {% f cancelUrl, 2 %} | `string` | The URL to redirect the payer to if the payment is cancelled, either by the payer or by the merchant trough an `abort` request of the `payment` or `paymentorder`. | +| {% icon check %} | {% f callbackUrl, 2 %} | `string` | {% include fields/callback-url.md %} | +| | {% f logoUrl, 2 %} | `string` | {% include fields/logo-url.md %} | +| {% icon check %} | {% f orderItems %} | `array` | {% include fields/order-items.md %} | +| {% icon check %} | {% f reference, 2 %} | `string` | A reference that identifies the order item. | +| {% icon check %} | {% f name, 2 %} | `string` | The name of the order item. | +| {% icon check %} | {% f type, 2 %} | `enum` | `PRODUCT`, `SERVICE`, `SHIPPING_FEE`, `DISCOUNT`, `VALUE_CODE`, or `OTHER`. The type of the order item. | +| {% icon check %} | {% f class, 2 %} | `string` | The classification of the order item. Can be used for assigning the order item to a specific product category, such as `MobilePhone`. Note that `class` cannot contain spaces and must follow the regex pattern `[\w-]*`. Swedbank Pay may use this field for statistics. | +| | {% f itemUrl, 2 %} | `string` | The URL to a page that can display the purchased item, such as a product page | +| | {% f imageUrl, 2 %} | `string` | The URL to an image of the order item. | +| | {% f description, 2 %} | `string` | The human readable description of the order item. | +| | {% f discountDescription, 2 %}| `string` | The human readable description of the possible discount. | +| {% icon check %} | {% f quantity, 2 %} | `number` | The 4 decimal precision quantity of order items being purchased. | +| {% icon check %} | {% f quantityUnit, 2 %} | `string` | The unit of the quantity, such as `pcs`, `grams`, or similar. | +| {% icon check %} | {% f unitPrice, 2 %} | `integer` | The price per unit of order item, including VAT. | +| | {% f discountPrice, 2 %} | `integer` | If the order item is purchased at a discounted price. This field should contain that price, including VAT. | +| {% icon check %} | {% f vatPercent, 2 %} | `integer` | The percent value of the VAT multiplied by 100, so `25%` becomes `2500`. | +| {% icon check %} | {% f amount, 2 %} | `integer` | {% include fields/amount.md %} | +| {% icon check %} | {% f vatAmount, 2 %} | `integer` | {% include fields/vat-amount.md %} | +| {% icon check %} | {% f payeeInfo %} | `string` | {% include fields/payee-info.md %} | +| {% icon check %} | {% f payeeId, 2 %} | `string` | The ID of the payee, usually the merchant ID. | +| {% icon check %} | {% f payeeReference, 2 %} | `string` | {% include fields/payee-reference.md describe_receipt=true %} | +| | {% f payeeName, 2 %} | `string` | The name of the payee, usually the name of the merchant. | +| | {% f orderReference, 2 %} | `string(50)` | The order reference should reflect the order reference found in the merchant's systems. | +{% endcapture %} +{% include accordion-table.html content=table %} + +## Payment Order Response + +{:.code-view-header} +**Response** + +```http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "paymentorder": { + "id": "/psp/paymentorders/{{ page.payment_order_id }}", + "created": "2020-06-22T10:56:56.2927632Z", + "updated": "2020-06-22T10:56:56.4035291Z", + "operation": "Purchase", + "status": "Initialized", + "currency": "SEK", + "vatAmount": 375, + "amount": 1500, + "description": "Test Purchase", + "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1", + "language": "sv-SE", + "availableInstruments": [ + "CreditCard", + "Invoice-PayExFinancingSe", + "Invoice-PayMonthlyInvoiceSe", + "Swish", + "CreditAccount", + "Trustly" ], + "implementation": "PaymentsOnly", {% if include.integration_mode=="seamless-view" %} + "integration": "HostedView", {% endif %} {% if include.integration_mode=="redirect" %} + "integration": "Redirect", + {% endif %} + "instrumentMode": false, + "guestMode": false, + "payer": { + "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/payers" + }, + "orderItems": { + "id": "/psp/paymentorders/{{ page.payment_order_id }}/orderitems" + }, + "history": { + "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/history" + }, + "failed": { + "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/failed" + }, + "aborted": { + "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/aborted" + }, + "paid": { + "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/paid" + }, + "cancelled": { + "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/cancelled" + }, + "financialTransactions": { + "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/financialtransactions" + }, + "failedAttempts": { + "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/failedattempts" + }, + "metadata": { + "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/metadata" + } + }, + "operations": [ + { + "method": "GET", + "href": "{{ page.front_end_url }}/payment/menu/{{ page.payment_token }}?_tc_tid=30f2168171e142d38bcd4af2c3721959", + "rel": "redirect-checkout", + "contentType": "text/html" + }, + { + "method": "GET", + "href": "{{ page.front_end_url }}/payment/core/js/px.payment.client.js?token={{ page.payment_token }}&culture=nb-NO&_tc_tid=30f2168171e142d38bcd4af2c3721959", + "rel": "view-checkout", + "contentType": "application/javascript" + }, + { + "href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224", + "rel":"update-order", + "method":"PATCH", + "contentType":"application/json" + }, + { + "href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224", + "rel": "abort", + "method": "PATCH", + "contentType": "application/json" + } + ] + } +``` + +{% capture table %} +{:.table .table-striped .mb-5} +| Field | Type | Description | +| :----------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| {% f paymentOrder, 0 %} | `object` | The payment order object. | +| {% f id %} | `string` | {% include fields/id.md resource="paymentorder" %} | +| {% f created %} | `string` | The ISO-8601 date of when the payment order was created. | +| {% f updated %} | `string` | The ISO-8601 date of when the payment order was updated. | +| {% f operation %} | `string` | `Purchase` | +| {% f status %} | `string` | Indicates the payment order's current status. `Initialized` is returned when the payment is created and still ongoing. The request example above has this status. `Paid` is returned when the payer has completed the payment successfully. [See the `Paid` response]({{ features_url }}/technical-reference/status-models#paid). `Failed` is returned when a payment has failed. You will find an error message in [the `Failed` response]({{ features_url }}/technical-reference/status-models#failed). `Cancelled` is returned when an authorized amount has been fully cancelled. [See the `Cancelled` response]({{ features_url }}/technical-reference/status-models#cancelled). It will contain fields from both the cancelled description and paid section. `Aborted` is returned when the merchant has aborted the payment, or if the payer cancelled the payment in the redirect integration (on the redirect page). [See the `Aborted` response]({{ features_url }}/technical-reference/status-models#aborted). | +| {% f currency %} | `string` | The currency of the payment order. | +| {% f amount %} | `integer` | {% include fields/amount.md %} | +| {% f vatAmount %} | `integer` | {% include fields/vat-amount.md %} | +| {% f description %} | `string(40)` | {% include fields/description.md %} | +| {% f initiatingSystemUserAgent %} | `string` | {% include fields/initiating-system-user-agent.md %} | +| {% f language %} | `string` | {% include fields/language.md %} | +| {% f availableInstruments %} | `string` | A list of instruments available for this payment. | +| {% f implementation %} | `string` | The merchant's Digital Payments implementation type. `Enterprise` or `PaymentsOnly`. We ask that you don't build logic around this field's response. It is mainly for information purposes, as the implementation types might be subject to name changes. If this should happen, updated information will be available in this table. | +| {% f integration %} | `string` | The merchant's Digital Payments integration type. `HostedView` (Seamless View) or `Redirect`. This field will not be populated until the payer has opened the payment UI, and the client script has identified if Swedbank Pay or another URI is hosting the container with the payment iframe. We ask that you don't build logic around this field's response. It is mainly for information purposes. as the integration types might be subject to name changes, If this should happen, updated information will be available in this table. | +| {% f instrumentMode %} | `bool` | Set to `true` or `false`. Indicates if the payment is initialized with Instrument Mode (only one payment instrument available). | +| {% f guestMode %} | `bool` | Set to `true` or `false`. Indicates if the payer chose to pay as a guest or not. When using the Payments Only implementation, this is triggered by not including a `payerReference` in the original `paymentOrder` request. | +| {% f payer %} | `string` | The URL to the [`payer` resource]({{ features_url }}/technical-reference/resource-sub-models#payer) where information about the payer can be retrieved. | +| {% f orderItems %} | `string` | The URL to the `orderItems` resource where information about the order items can be retrieved. | +| {% f history %} | `string` | The URL to the [`history` resource]({{ features_url }}/technical-reference/resource-sub-models#history) where information about the payment's history can be retrieved. | +| {% f failed %} | `string` | The URL to the [`failed` resource]({{ features_url }}/technical-reference/resource-sub-models#failed) where information about the failed transactions can be retrieved. | +| {% f aborted %} | `string` | The URL to the [`aborted` resource]({{ features_url }}/technical-reference/resource-sub-models#aborted) where information about the aborted transactions can be retrieved. | +| {% f paid %} | `string` | The URL to the [`paid` resource]({{ features_url }}/technical-reference/resource-sub-models#paid) where information about the paid transactions can be retrieved. | +| {% f cancelled %} | `string` | The URL to the [`cancelled` resource]({{ features_url }}/technical-reference/resource-sub-models#cancelled) where information about the cancelled transactions can be retrieved. | +| {% f financialTransactions %} | `string` | The URL to the [`financialTransactions` resource]({{ features_url }}/technical-reference/resource-sub-models#financialtransactions) where information about the financial transactions can be retrieved. | +| {% f failedAttempts %} | `string` | The URL to the [`failedAttempts` resource]({{ features_url }}/technical-reference/resource-sub-models#failedattempts) where information about the failed attempts can be retrieved. | +| {% f metadata %} | `string` | The URL to the `metadata` resource where information about the metadata can be retrieved. | +| {% f operations %} | `array` | {% include fields/operations.md %} | +{% endcapture %} +{% include accordion-table.html content=table %} + +[instrument-mode]: /checkout-v3/features/optional/instrument-mode diff --git a/checkout-v3/payment-request-3-1.md b/checkout-v3/payment-request-3-1.md index f2f7db69e7..fe57e04295 100644 --- a/checkout-v3/payment-request-3-1.md +++ b/checkout-v3/payment-request-3-1.md @@ -17,22 +17,33 @@ When your customer has initiated a purchase, you need to create a payment order. Start by performing a `POST` request towards the `paymentorder` resource with payer information and a `completeUrl`. -We have added `productName` to the payment order request in this integration. -You can find it in the `paymentorder` field. This is required if you want to use -Digital Payments. If it isn´t included in your request, you won't get the -correct operations in the response. +The `productName` field has been removed as a mandatory field in v3.1, and you +identify the `paymentOrder` version as v3.1 in the header instead. -When `productName` is set to `checkout3`, `digitalProducts` will be set to -`false` by default. +`POST`, `PATCH` and `PUT` requests use this header: + +`Content-Type: application/json;version=3.1` + +`GET` requests use this header: + +`Accept: application/json;version=3.1` + +Valid versions are **3.1**, **3.0** and **2.0**. If you do not add a version, +the request will default to **2.0**. Using the `productName` and setting it to +`checkout3` will default to **3.0** + +To acompany the new basic request, we have also added a +[v3.1 post-purchase section][post-31], [v3.1 callback][callback-31] and a new +[resource model for `failedPostPurchaseAttempts`][fppa]. Supported features for this integration are subscriptions (`recur`, `one-click` and `unscheduled MIT`), `MOTO`, instrument mode, split settlement (`subsite`) and the possibility to use your own `logo`. There is also a guest mode option for the payers who don't wish to store their -information. When using **Payments Only**, the way to trigger this is to not -include the `payerReference` field in your `paymentOrder` request. You can find -it in the `payer` field in the example below. +information. The way to trigger this is to not include the `payerReference` +field in your `paymentOrder` request. If the `payer` field is included in your +request, you can find the `payerReference` there. Sometimes you might need to abort purchases. An example could be if a payer does not complete the purchase within a reasonable timeframe. For those instances we @@ -64,6 +75,9 @@ Read more about possible additions to the request in our next_title="Display Payment UI" %} [abort-feature]: /checkout-v3/features/core/abort +[callback-31]: /checkout-v3/features/core/callback [features]: /checkout-v3/features/ +[fppa]: /checkout-v3/features/technical-reference/resource-sub-models#failedpostpurchaseattempts-31-only [frictionless]: /checkout-v3/features/core/frictionless-payments [order-items]: /checkout-v3/features/optional/order-items +[post-31]: /checkout-v3/post-purchase-3-1 diff --git a/checkout-v3/payment-request.md b/checkout-v3/payment-request.md index 64eaed2612..2e098f1ea2 100644 --- a/checkout-v3/payment-request.md +++ b/checkout-v3/payment-request.md @@ -18,9 +18,19 @@ Start by performing a `POST` request towards the `paymentorder` resource with payer information and a `completeUrl`. We have added `productName` to the payment order request in this integration. -You can find it in the `paymentorder` field. This is required if you want to use -Digital Payments. If it isn´t included in your request, you won't get the -correct operations in the response. +You can find it in the `paymentorder` field. This is no longer required, but is +still an option to use v3.0 of Digital Payments. To use `productName`, simply +put `Checkout3` as the value in that field in the request. You can also specify +version by adding it in the header instead. If you use this option, you can +leave out the `productName` field. + +`POST`, `PATCH` and `PUT` requests use this header: + +`Content-Type: application/json;version=3.0` + +`GET` requests use this header: + +`Accept: application/json;version=3.0` When `productName` is set to `checkout3`, `digitalProducts` will be set to `false` by default. @@ -30,9 +40,9 @@ and `unscheduled MIT`), `MOTO`, instrument mode, split settlement (`subsite`) and the possibility to use your own `logo`. There is also a guest mode option for the payers who don't wish to store their -information. When using **Payments Only**, the way to trigger this is to not -include the `payerReference` field in your `paymentOrder` request. You can find -it in the `payer` field in the example below. +information. The way to trigger this is to not include the `payerReference` +field in your `paymentOrder` request. If the `payer` field is included in your +request, you can find the `payerReference` there. Sometimes you might need to abort purchases. An example could be if a payer does not complete the purchase within a reasonable timeframe. For those instances we