Payment-Start-v2: Difference between revisions
mNo edit summary |
|||
(27 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
{{PageTitle|title=Barion API: Initialize a new payment}} | {{PageTitle|title=Barion API: Initialize a new payment}} | ||
Line 28: | Line 27: | ||
{| | {| | ||
|- | |- | ||
|{{3dsfield}} || Properties marked with this must be provided to comply with 3D Secure authentication. | |{{3dsfield}} || Properties marked with this must be provided to comply with 3D Secure authentication. The more attributes you provide the more chance you have to avoid the challenge flow. | ||
|- | |- | ||
|} | |} | ||
'''Important:''' if the merchant does not provide 3DS-related properties, it doesn't mean that the payment will fail. It means that the payer will have a higher chance of getting a challenge during payment. | |||
{{api_input_table_header}} | {{api_input_table_header}} | ||
Line 45: | Line 45: | ||
** "Immediate" | ** "Immediate" | ||
** "Reservation" | ** "Reservation" | ||
** "DelayedCapture" | ** "DelayedCapture" | ||
|| The type of | || The type of payment, which can be either immediate or a money reservation. Reservation means that the shop has a time window to finish the payment (even though the money transaction still takes place immediately). Reservation amounts can be modified during this time window unless the new amount is lower than the original. | ||
Click here to learn more about reservation payments: [[Reservation_payment|Reservation payments]] | Click here to learn more about reservation payments: [[Reservation_payment|Reservation payments]], and delayed capture: [[Delayed_Capture|Delayed capture]]. | ||
|- | |- | ||
| ReservationPeriod || TimeSpan (d | | ReservationPeriod || TimeSpan (d.hh:mm:ss) || | ||
* Required only if PaymentType is "Reservation" | * Required only if PaymentType is "Reservation" | ||
* Minimum value: one minute | * Minimum value: one minute | ||
Line 60: | Line 60: | ||
|- | |- | ||
| DelayedCapturePeriod | | DelayedCapturePeriod || TimeSpan (d.hh:mm:ss) || | ||
* Required only if PaymentType is "DelayedCapture" | * Required only if PaymentType is "DelayedCapture" | ||
* Minimum value: one minute | * Minimum value: one minute | ||
Line 69: | Line 69: | ||
|- | |- | ||
| PaymentWindow || TimeSpan (d | | PaymentWindow || TimeSpan (d.hh:mm:ss) || | ||
* Optional | * Optional | ||
* Minimum value: one minute | * Minimum value: one minute | ||
Line 80: | Line 80: | ||
| GuestCheckOut || bool || | | GuestCheckOut || bool || | ||
* Required | * Required | ||
* Value must be "true" or "false", integer | * Value must be "true" or "false", integer evaluation is not supported | ||
|| Flag indicating | || Flag indicating whether the payment can be completed without a registered Barion wallet. Guest checkout can only be done with bank cards, and the payer must supply a valid e-mail address - this is necessary for fraud control. | ||
|- | |- | ||
Line 87: | Line 87: | ||
| InitiateRecurrence || bool || | | InitiateRecurrence || bool || | ||
* Optional | * Optional | ||
|| This flag indicates that the shop would like to initialize a token payment. This means that the shop is authorized to charge the funding source of the payer in the future without redirecting her/him to the Barion Smart Gateway. It can be used for one-click and | || This flag indicates that the shop would like to initialize a token payment. This means that the shop is authorized to charge the funding source of the payer in the future without redirecting her/him to the Barion Smart Gateway. It can be used for one-click and subscription payment scenarios. | ||
Click here to learn more about token payments: [[Token_payment]] | Click here to learn more about token payments: [[Token_payment]] | ||
Line 93: | Line 93: | ||
| RecurrenceId || string || | | RecurrenceId || string || | ||
* Required when executing | * Required when executing token payments | ||
* Maximum length: 100 characters | * Maximum length: 100 characters | ||
* Must be unique per shop and per user | * Must be unique per shop and per user | ||
|| A string used to identify a given | * [https://docs.barion.com/Token_payment#Creating_the_token Generated by the shop] | ||
* If '''InitiateRecurrence''' is <code>true</code>, this property must contain a <u>new</u> desired identifier for a new | || A string used to identify a given token payment. Its purpose is determined by the value of the '''InitiateRecurrence''' property. | ||
* If '''InitiateRecurrence''' is <code>false</code>, this property must contain an <u>existing</u> identifier for | * If '''InitiateRecurrence''' is <code>true</code>, this property must contain a <u>new</u> desired identifier for a new token payment. This should be generated and stored by the shop before calling the API. Also, the shop must ensure that this is unique per user in its own system. | ||
* If '''InitiateRecurrence''' is <code>false</code>, this property must contain an <u>existing</u> identifier for a token payment. This should be used to charge a payer's funding source (either bank card or Barion wallet) that was already used successfully for a payment in the shop. | |||
|- | |- | ||
| FundingSources || string[] || | | FundingSources || string[] || | ||
Line 107: | Line 110: | ||
** "Balance" | ** "Balance" | ||
|| An array of strings containing the allowed funding sources that can be used to complete the payment. "Balance" means that the payer can only use their Barion wallet balance, while "All" means the payment can be completed with either a Barion wallet or a bank card. | || An array of strings containing the allowed funding sources that can be used to complete the payment. "Balance" means that the payer can only use their Barion wallet balance, while "All" means the payment can be completed with either a Barion wallet or a bank card. | ||
'''Note:''' There is no option to disallow payment by balance | '''Note:''' There is no option to disallow payment by balance since that would deny Barion Wallet users with a balance the ability to pay. There is an option to exclude cards, but not balance. | ||
'''Note:''' this must be supplied as an array | '''Note:''' this must be supplied as an array because more funding source types are planned in the future. | ||
|- | |- | ||
Line 118: | Line 121: | ||
|- | |- | ||
| PayerHint || string || | | PayerHint || string || | ||
* Required for {{3dsfield}} | * Required for {{3dsfield}} | ||
* Optional | * Optional, but recommended | ||
* Maximum length: 256 characters | * Maximum length: 256 characters | ||
|| The shop can | || The shop can supply an e-mail address as a hint on who should complete the payment. This can be used if the shop is certain about that the payer has an active Barion wallet or the shop would like to help the guest payer with filling in the email field for her/him. If provided, the Barion Smart Gateway automatically fills out the e-mail address field in the Barion wallet login form and the guest payer form, speeding up the payment process. | ||
|- | |- | ||
| CardHolderNameHint || string || | | CardHolderNameHint || string || | ||
* Required for {{3dsfield}} | * Required for {{3dsfield}} | ||
* Optional, but recommended | |||
* Between 2 and 45 characters | * Between 2 and 45 characters | ||
|| The shop | || The shop can provide a hint for the customer's name on the card to speed up the payment flow. If a value is provided, the cardholder name input will be pre-filled with it and the customer can use the pre-filled value instead of typing it out on its own, which speeds up the payment process. | ||
|- | |||
| RecurrenceType || [[RecurrenceType]] || | |||
* Required for {{3dsfield}}, when executing token payments | |||
|| Describes the nature of the token payment. | |||
|- | |||
|- | |||
| TraceId || string || | |||
* Required for {{3dsfield}}, when executing token payments | |||
* Maximum length: 100 characters | |||
|| Identifies the nature of the token payment. | |||
|- | |- | ||
Line 136: | Line 155: | ||
* Required | * Required | ||
* Maximum length: 2000 characters | * Maximum length: 2000 characters | ||
|| The URL where the payer should be redirected after the payment is completed or | || The URL where the payer should be redirected after the payment is completed or canceled. The payment identifier is added to the query string part of this URL in the <code>paymentId</code> parameter. If not provided, the system will use the redirect URL assigned to the shop that started the payment. | ||
|- | |- | ||
Line 157: | Line 176: | ||
* Optional | * Optional | ||
* Maximum length: 100 characters | * Maximum length: 100 characters | ||
|| The order number generated by the shop. This is to aid the shop in identifying a given payment in | || The order number generated by the shop. This is to aid the shop in identifying a given payment in its own system. This also shows up in generated monthly account statements and transaction history exports, so it also helps with bookkeeping. | ||
|- | |- | ||
Line 163: | Line 182: | ||
| ShippingAddress || [[ShippingAddress]] || | | ShippingAddress || [[ShippingAddress]] || | ||
* Required for {{3dsfield}} | * Required for {{3dsfield}} | ||
|| The shipping address associated with the payment, if applicable. Providing this is recommended | || The shipping address associated with the payment, if applicable. Providing this is recommended because it helps the automatic anti-fraud analysis get more accurate results. See the [[ShippingAddress]] page for the appropriate structure and syntax. | ||
|- | |- | ||
Line 179: | Line 198: | ||
** "sk-SK" (Slovak) | ** "sk-SK" (Slovak) | ||
** "sl-SI" (Slovenian) | ** "sl-SI" (Slovenian) | ||
|| This indicates in which language the Barion Smart Gateway should display for the payer upon redirect. | || This indicates in which language the Barion Smart Gateway should display for the payer upon redirect. | ||
|- | |- | ||
Line 186: | Line 204: | ||
* Required | * Required | ||
* Required length: 3 characters | * Required length: 3 characters | ||
Accepted values: | |||
{{CurrencyList}} | |||
|| The currency of the payment. Must be supplied in ISO 4217 format. This affects all transactions included in the payment; it is not possible to define multiple transactions in different currencies. | || The currency of the payment. Must be supplied in ISO 4217 format. This affects all transactions included in the payment; it is not possible to define multiple transactions in different currencies. | ||
|- | |- | ||
Line 196: | Line 211: | ||
* Required for {{3dsfield}} | * Required for {{3dsfield}} | ||
* Max length: 30 characters | * Max length: 30 characters | ||
* Expected format: 36701231234 | * Expected format: 36701231234 (where 36 is the country code) | ||
* Required for using payment buttons | * Required for using payment buttons | ||
|| The phone number of the payer. Must be set to enable [[Payment_Buttons|payment buttons]]. | || The '''mobile''' phone number of the payer. Must be set to enable [[Payment_Buttons|payment buttons]]. The number must be sent in the expected format, without + sign or leading zero(s). | ||
|- | |- | ||
| PayerWorkPhoneNumber || string || | | PayerWorkPhoneNumber || string || | ||
* Required for {{3dsfield}} | * Required for {{3dsfield}} | ||
* Max length: 30 characters | * Max length: 30 characters | ||
* Expected format: 36701231234 | * Expected format: 36701231234 (where 36 is the country code) | ||
|| The work phone of the payer | || The work phone of the payer. The number must be sent in the expected format, without + sign or leading zero(s). | ||
|- | |- | ||
| PayerHomeNumber || string || | | PayerHomeNumber || string || | ||
* Required for {{3dsfield}} | * Required for {{3dsfield}} | ||
* Max length: 30 characters | * Max length: 30 characters | ||
* Expected format: 36701231234 | * Expected format: 36701231234 (where 36 is the country code) | ||
|| The home phone number of the payer. | || The home phone number of the payer. The number must be sent in the expected format, without + sign or leading zero(s). | ||
|- | |- | ||
| BillingAddress || [[BillingAddress]] || | | BillingAddress || [[BillingAddress]] || | ||
Line 226: | Line 241: | ||
|| Information about current purchase. | || Information about current purchase. | ||
|- | |- | ||
| ChallengePreference || [[ChallengePreference]] || | |||
* Required for {{3dsfield}} | |||
|| The merchant's preference of the 3DS challenge. Here you can specify what 3DS authentication should be utilized. | |||
|- | |||
|} | |} | ||
Line 253: | Line 274: | ||
* If '''InitiateRecurrence''' was <code>true</code>, and a new authorized payment was successfully created, this will be <code>None</code> (because no actual token charge took place yet) | * If '''InitiateRecurrence''' was <code>true</code>, and a new authorized payment was successfully created, this will be <code>None</code> (because no actual token charge took place yet) | ||
* If '''InitiateRecurrence''' was <code>false</code>, but a previously authorized payment identifier was supplied in '''RecurrenceId''', the system will try to charge the funding source associated with the authorized payment. If this charge is successful, the result is <code>Successful</code>. If the system could not charge the funding | * If '''InitiateRecurrence''' was <code>false</code>, but a previously authorized payment identifier was supplied in '''RecurrenceId''', the system will try to charge the funding source associated with the authorized payment. If this charge is successful, the result is <code>Successful</code>. If the system could not charge the funding source, the result is <code>Failed</code>. If the given identifier is invalid or does not exist, the result is <code>NotFound</code>. In case the payment can not be processed due to lack of 3DS v2 information <code>ThreeDSAuthenticationRequired</code> is returned. In this case, either offsite 3DS v2 authentication should be performed or the TraceId of the initial payment should be sent as well. | ||
|- | |- |
Revision as of 17:36, 19 February 2021
Barion API: Initialize a new payment
POST | /v2/Payment/Start |
---|
The /payment/start
API endpoint is used to create a new payment in the Barion system.
Prerequisites before use:
v2 This API endpoint is available in API v2 only.
Use cases
This API endpoint is designed to be used in the following scenarios:
Input properties
3DS |
Properties marked with this must be provided to comply with 3D Secure authentication. The more attributes you provide the more chance you have to avoid the challenge flow. |
Important: if the merchant does not provide 3DS-related properties, it doesn't mean that the payment will fail. It means that the payer will have a higher chance of getting a challenge during payment.
Property name | Property type | Limitations and constraints | Description |
---|---|---|---|
POSKey | Guid |
|
The secret API key of the shop, generated by Barion. This lets the shop to authenticate through the Barion API, but does not provide access to the account owning the shop itself. |
PaymentType | string |
|
The type of payment, which can be either immediate or a money reservation. Reservation means that the shop has a time window to finish the payment (even though the money transaction still takes place immediately). Reservation amounts can be modified during this time window unless the new amount is lower than the original.
Click here to learn more about reservation payments: Reservation payments, and delayed capture: Delayed capture. |
ReservationPeriod | TimeSpan (d.hh:mm:ss) |
|
Only makes sense at reservation payments. This is the time window that allows the shop to finish (finalize) the payment. If this does not happen within the time window, the system refunds the payment amount to the payer. |
DelayedCapturePeriod | TimeSpan (d.hh:mm:ss) |
|
This is the time window that allows the shop to complete (finalize) the payment. If this does not happen within the time window, the system releases the payment amount. |
PaymentWindow | TimeSpan (d.hh:mm:ss) |
|
Time window for the payment to be completed. The payer must execute the payment before this elapses, or else the payment will expire and can no longer be completed. |
GuestCheckOut | bool |
|
Flag indicating whether the payment can be completed without a registered Barion wallet. Guest checkout can only be done with bank cards, and the payer must supply a valid e-mail address - this is necessary for fraud control. |
InitiateRecurrence | bool |
|
This flag indicates that the shop would like to initialize a token payment. This means that the shop is authorized to charge the funding source of the payer in the future without redirecting her/him to the Barion Smart Gateway. It can be used for one-click and subscription payment scenarios.
Click here to learn more about token payments: Token_payment |
RecurrenceId | string |
|
A string used to identify a given token payment. Its purpose is determined by the value of the InitiateRecurrence property.
|
FundingSources | string[] |
|
An array of strings containing the allowed funding sources that can be used to complete the payment. "Balance" means that the payer can only use their Barion wallet balance, while "All" means the payment can be completed with either a Barion wallet or a bank card.
Note: There is no option to disallow payment by balance since that would deny Barion Wallet users with a balance the ability to pay. There is an option to exclude cards, but not balance. Note: this must be supplied as an array because more funding source types are planned in the future. |
PaymentRequestId | string |
|
The unique identifier for the payment generated by the shop. This is so the shop can track its own payment identifiers. It is also useful for bookkeeping purposes since this shows up in the monthly account statement and the transaction history export, making identification of payments easier for the shop. |
PayerHint | string |
|
The shop can supply an e-mail address as a hint on who should complete the payment. This can be used if the shop is certain about that the payer has an active Barion wallet or the shop would like to help the guest payer with filling in the email field for her/him. If provided, the Barion Smart Gateway automatically fills out the e-mail address field in the Barion wallet login form and the guest payer form, speeding up the payment process. |
CardHolderNameHint | string |
|
The shop can provide a hint for the customer's name on the card to speed up the payment flow. If a value is provided, the cardholder name input will be pre-filled with it and the customer can use the pre-filled value instead of typing it out on its own, which speeds up the payment process. |
RecurrenceType | RecurrenceType |
|
Describes the nature of the token payment. |
TraceId | string |
|
Identifies the nature of the token payment. |
RedirectUrl | string |
|
The URL where the payer should be redirected after the payment is completed or canceled. The payment identifier is added to the query string part of this URL in the paymentId parameter. If not provided, the system will use the redirect URL assigned to the shop that started the payment.
|
CallbackUrl | string |
|
The URL where the Barion system sends a request whenever there is a change in the state of the payment. The payment identifier is added to the query string part of this URL in the paymentId parameter. Click here to learn more about the callback mechanism: Payment callback mechanism (IPN)
|
Transactions | PaymentTransaction[] |
|
An array of payment transactions contained in the payment. A payment must contain at least one such transaction. See the PaymentTransaction page for the appropriate structure and syntax.
Defining multiple transactions allow the payment initiator to distribute the payment amount between multiple shops. See the following page to learn more: Facilitated payments |
OrderNumber | string |
|
The order number generated by the shop. This is to aid the shop in identifying a given payment in its own system. This also shows up in generated monthly account statements and transaction history exports, so it also helps with bookkeeping. |
ShippingAddress | ShippingAddress |
|
The shipping address associated with the payment, if applicable. Providing this is recommended because it helps the automatic anti-fraud analysis get more accurate results. See the ShippingAddress page for the appropriate structure and syntax. |
Locale | string |
|
This indicates in which language the Barion Smart Gateway should display for the payer upon redirect. |
Currency | string |
Accepted values:
|
The currency of the payment. Must be supplied in ISO 4217 format. This affects all transactions included in the payment; it is not possible to define multiple transactions in different currencies. |
PayerPhoneNumber | string |
|
The mobile phone number of the payer. Must be set to enable payment buttons. The number must be sent in the expected format, without + sign or leading zero(s). |
PayerWorkPhoneNumber | string |
|
The work phone of the payer. The number must be sent in the expected format, without + sign or leading zero(s). |
PayerHomeNumber | string |
|
The home phone number of the payer. The number must be sent in the expected format, without + sign or leading zero(s). |
BillingAddress | BillingAddress |
|
The billing address associated with the payment, if applicable. |
PayerAccount | PayerAccountInformation |
|
Information about the account of the payer in the merchant's system. |
PurchaseInformation | PurchaseInformation |
|
Information about current purchase. |
ChallengePreference | ChallengePreference |
|
The merchant's preference of the 3DS challenge. Here you can specify what 3DS authentication should be utilized. |
Output properties
Property name | Property type | Description |
---|---|---|
PaymentId | Guid | The identifier of the newly initialized payment, generated by the Barion system. |
PaymentRequestId | string | The payment identifier supplied by the API caller in the request. |
Status | PaymentStatus | The status of the payment in the Barion system. |
QRUrl | string | URL for a QR code representing the payment. This is useful in physical real life situations where the payer uses a mobile device. |
RecurrenceResult | RecurrenceResult | Indicates the result of an authorized payment scenario. The result depends on the values of the InitiateRecurrence and RecurrenceId properties supplied in the request.
|
Transactions | ProcessedTransaction[] | An array containing all transactions associated with the payment. If the Barion system deducts fees from the shop after payments, this also contains these additional fee transactions beside the payment transactions that were sent in the request. |
GatewayUrl | string | The URL of the Barion Smart Gateway (including the payment identifier), where the API caller should redirect the payer. |
CallbackUrl | string | The URL (including the payment identifier) where the Barion system will send a request to whenever there is a change in the state of the payment. If an explicit URL was not supplied, this will be the callback URL associated with the shop that started the payment. |
RedirectUrl | string | The URL (including the payment identifier) where the payer gets redirected to after the payment is completed or cancelled. If an explicit URL was not supplied, this will be the redirect URL associated with the shop that started the payment. |