Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Describe payment card support #36

Merged
merged 16 commits into from Jun 22, 2020
Merged

Describe payment card support #36

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
01191d7
add docs payment card
zdrazil Jun 16, 2020
70fa5ef
Apply suggestions from code review
zdrazil Jun 18, 2020
390a412
shorten
zdrazil Jun 18, 2020
1ca5c0e
rephrase
zdrazil Jun 18, 2020
99dca59
update payment gateway
zdrazil Jun 18, 2020
08ee9b4
update
zdrazil Jun 18, 2020
e1091b5
improve wording
zdrazil Jun 19, 2020
eae5758
improve wording
zdrazil Jun 19, 2020
cc036f1
add detail
zdrazil Jun 19, 2020
6eba9fe
update
zdrazil Jun 19, 2020
39ae22b
update
zdrazil Jun 19, 2020
25104a9
update
zdrazil Jun 19, 2020
321ba9b
shorten
zdrazil Jun 19, 2020
d7be78e
fix casing
zdrazil Jun 19, 2020
453791b
update
zdrazil Jun 19, 2020
6bd98d0
Update changelog.md
zdrazil Jun 22, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
7 changes: 7 additions & 0 deletions distributor-api-v1/changelog.md
View file
Open in desktop
@@ -1,5 +1,12 @@
# Changelog

## 22.06.2020

* Added section describing payment card support.
* Improved `PaymentGatewayData` description.
* Removed deprecated payment gateways.
* Improved `CreditCardData` description.

## 22.04.2020

* Added following sections: Configuration, Theme, City, PaymentCardInput, RequiredField, Enterprise and Address.
Expand Down
43 changes: 43 additions & 0 deletions distributor-api-v1/general-guidelines.md
View file
Open in desktop
Expand Up @@ -41,3 +41,46 @@ In case of any error, the returned JSON object describes the error and has the f

Some errors may also contain additional information relevant to the error on top of this two properties. But that depends on the operation and is specificly described in the operation documentation.

## How to support payment cards in custom Distributor client

As part of creating your own custom Distributor client you may want to have a form within your client where customers can enter their payment card data and send this data to Distributor API for further use. Payment card data can then be used by Mews in several ways for example for charging the customer.

To do that some Distributor API endpoints support or require [CreditCardData](operations.md#creditcarddata) (represents payment card data with name `CreditCardData` for legacy and compatibility reasons) in the request. You can visit [Operations](operations.md) to see which endpoints they are.

To send the correct [CreditCardData](operations.md#creditcarddata) you need (check the [docs](operations.md#creditcarddata) to see which fields are required):
* Card holder name
* Card number
* CVV
* Expiration date

This is the relation between the human readable names and the field names which Distributor API uses:

| Human readable | Distributor API |
| :------------------ | :-------------------- |
| Card holder name | `HolderName` |
| Card number | `PaymentGatewayData` |
| Expiration date | `Expiration` |
| CVV | `PaymentGatewayData` |

`Expiration` and `HolderName` are not sensitive data in terms of PCI DSS and plain text can be used. The `Expiration` does need to follow the format described in [CreditCardData](operations.md#creditcarddata).

[PaymentGatewayData](payment-gateway-data.md) is a string representing some card data (CVV and card number) which are encoded via payment card storage provider. Those card data are sensitive in terms of PCI DSS and therefore the implementation should not handle them in plain text.

### To add payment cards support

Please be aware that names of fields in PCI Proxy and Distributor API differ but they represent the same things:

| Distributor API | PCI Proxy |
| :----------------- | :------------ |
| `PublicKey` | `merchantId` |
| `PaymentGatewayData` | `transactionId` |

* Confirm that property supports PCI Proxy by checking the field [PaymentCardStorageType](operations.md#paymentcardstoragetype) in Distributor API response. Also read docs about [PaymentGateway](operations.md#payment-gateway) to see what other API data you could potentially use for your implemention.
* Use [PublicKey](operations.md#payment-gateway) as `merchantId` and PCI Proxy with their [guide](https://docs.pci-proxy.com/collect-and-store-cards/capture-iframes) to handle the sensitive card data and to obtain `PaymentGatewayData`.
* Use `transactionId` from PCI Proxy as `PaymentGatewayData` inside [CreditCardData](operations.md#creditcarddata).

| Distributor API Field | Used in | Source |
| :----------------- | :------------ | :----- |
| `PublicKey` | PCI Proxy | Distributor API |
| `PaymentGatewayData` | Distributor API | PCI Proxy |

12 changes: 5 additions & 7 deletions distributor-api-v1/operations.md
View file
Open in desktop
Expand Up @@ -511,8 +511,6 @@ If the hotel does not use any payment gateway, the value is null. If it does, th

#### PaymentCardStorageType

* Adyen
* Stripe
* PciProxy

#### CreditCardType
Expand Down Expand Up @@ -995,8 +993,8 @@ Gives a pricing information for the given configuration.
],
"CreditCardData": {
"PaymentGatewayData": "...",
"ObfuscatedCreditCardNumber": "411111******1111",
"Expiration": "2020-10"
"Expiration": "2030-10"
"HolderName": "John Smith",
}
}
```
Expand Down Expand Up @@ -1055,9 +1053,9 @@ Gives a pricing information for the given configuration.

| | Property | Type | Description |
| :--- | :--- | :--- | :--- |
| `PaymentGatewayData` | string | required | Encoded credit card data obtained from the payment gateway specific library. More details [here](payment-gateway-data.md). |
| `ObfuscatedCreditCardNumber` | string | required | Obfuscated credit card number, e.g.`411111******1111`. |
| `Expiration` | string | required | Expiration of credit card in format `YYYY-MM`. Required with PCI Proxy payment gateway type. |
| `PaymentGatewayData` | string | required | Encoded payment card data obtained from the payment gateway specific library. More details [here](payment-gateway-data.md). |
| `Expiration` | string | required | Expiration of payment card in format `YYYY-MM`. |
zdrazil marked this conversation as resolved.
Show resolved Hide resolved
| `HolderName` | string | required | Card holder name. |

### Response <a id="response-6"></a>

Expand Down
7 changes: 3 additions & 4 deletions distributor-api-v1/payment-gateway-data.md
View file
Open in desktop
@@ -1,8 +1,7 @@
# Payment Gateway Data

To obtain`PaymentGatewayData`, you have to use client side encryption library provided by given payment gateway. You can find them here:
`PaymentGatewayData` is an encoded representation of card number and CVV which is used to provide payment card data to Distributor API.

* [Adyen](https://github.com/Adyen/CSE-JS)
* [Stripe](https://stripe.com/docs/stripe.js)
* [PCI Proxy](https://docs.pci-proxy.com/collect-and-store-cards/capture-iframes)
You can use a combination of [PCI Proxy client side encryption library](https://docs.pci-proxy.com/collect-and-store-cards/capture-iframes) and your own custom implementation of Distributor client to obtain in.
zdrazil marked this conversation as resolved.
Show resolved Hide resolved

You can then use it to [add payment cards support to custom Distributor client](general-guidelines.md#howtosupportpaymentcardsincustomdistributorclient).
18 changes: 9 additions & 9 deletions distributor-widget/advanced-guide.md
View file
Open in desktop
Expand Up @@ -93,19 +93,19 @@ In addition, Distributor in multihotel mode also supports:

The deeplinks are also supported by standalone Distributor.

### Payment Gateways <a id="payment-gateways"></a>
### Payment card storages

Payment gateway is used to safely collect information about a customer’s credit card. A configuration is done once, when the hotel is set up. Distributor would use it automatically. Currently Distributor supports these gateways:
Payment card storage is used to safely collect and store information about a customer's payment card. Currently Distributor supports these payment card storages:

* [Braintree](https://www.braintreepayments.com/)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was this outdated?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

as @mveith mentioned PCI Proxy is no longer a gateway but payment card storage so we might want to fix the title and description of this section as well

* [Adyen](https://www.adyen.com/home)
* Mews Merchant
* [PCI Proxy](https://www.pci-proxy.com)

Using payment gateway is not mandatory, as reservations can be created without providing a credit card information.
### Payment gateways

**Important:** PCI Security Standard requires you to use **SSL Certificate** on your website to be allowed to collect any payments info. This happens when using Braintree or Adyen gateways.
Payment gateway is used to securely handle customer payments. A configuration is done once, when the property is set up. Official Mews Distributor client can use it with minimal setup. Currently Distributor supports these payment gateways:

#### Mews Merchant <a id="mews-merchant"></a>
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it correct that this information is outdated and can be removed?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in person discussion: yep

* [Mews Merchant](https://www.mews.com/products/merchant)

When using the Mews Merchant gateway integration in Distributor on your website, a customer will be redirected to a mirroring Distributor hosted at [https://wwww.mews.li/](https://wwww.mews.li/) just before entering their payment details. This is a requirement when using Mews Merchant. When closing the Distributor, the customer will be redirected back to your website
Using payment gateway is not mandatory, as reservations can be created without providing a payment card information.

**Important:** PCI Security Standard requires you to use **SSL Certificate** on your website to be allowed to collect any payments info.