Payment-Start-v2-old: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
No edit summary
 
(53 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{| style="margin-left:2em;" align="right"
{{PageTitle|title=Barion API: Initialize a new payment}}
| __TOC__
 
|}
{{TableOfContents}}


{{PageTitle|title=Barion API: Initialize a new payment}}
{{NotificationBox|title=WARNING|text=The structure of this API call has been changed due to 3D Secure / PSD2 regulations! You can access the new structure here: [[Payment-Start-v2]]|color=#FF0000}}


{{api_callmethod
{{api_callmethod
Line 13: Line 13:


Prerequisites before use:
Prerequisites before use:
* [[Integrating the Barion Smart Gateway]]
* [[Creating_an_account|Creating an account in Barion]]
* [[Registering your shop in Barion]]
* [[Creating_a_shop|Creating a shop in Barion]]
* [[Calling the Barion API]]
* [[Calling_the_API|Calling the Barion API]]
 


<span class="api-ver">v2</span> This API endpoint is available in '''API v2''' only.
<span class="api-ver">v2</span> This API endpoint is available in '''API v2''' only.


== Use cases ==  
== Use cases ==


This API endpoint is designed to be used in the following scenarios:
This API endpoint is designed to be used in the following scenarios:
* [[Simple-Webshop-Integration|Simple Webshop Integration]]
* [[Responsive_web_payment|Responsive Web Payment]]


== Input properties ==
== Input properties ==
Line 39: Line 40:
** "Immediate"
** "Immediate"
** "Reservation"
** "Reservation"
|| The type of the 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.  
** "DelayedCapture"
Click here to learn more about reservation payments: [[Reservation payments]]
|| The type of the payment, which can be either immediate, money reservation or delayed capture. 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 delayed capture payments: [[Delayed_Capture|Delayed capture]]
|-
|-


| ReservationPeriod || TimeSpan (d:hh:mm:ss) ||  
| 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 53: Line 56:
|-
|-


| PaymentWindow || TimeSpan (d:hh:mm:ss) ||  
| DelayedCapturePeriod || TimeSpan (d.hh:mm:ss) ||
* Required only if PaymentType is "DelayedCapture"
* Minimum value: one minute
* Maximum value: 21 days
|| 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. The maximum time window depends on the country of the shop: 21 for Hungarian shops, 7 for everybody else
 
|-
 
| PaymentWindow || TimeSpan (d.hh:mm:ss) ||  
* Optional
* Optional
* Minimum value: one minute
* Minimum value: one minute
* Maximum value: one week
* Maximum value: one week
* Default value: 30 minutes
* Default value: 30 minutes
|| 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.
|| Time window for the payment to be completed by the payer. The payer must execute the payment before this elapses, or else the payment will expire and can no longer be completed.


|-
|-
Line 71: Line 82:
| InitiateRecurrence || bool ||  
| InitiateRecurrence || bool ||  
* Optional
* Optional
|| This flag indicates that the shop would like to initialize an authorized payment. This means that the shop is authorized to charge the funding source of the payer in the future without any user interaction.  
|| 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 susbscription payment scenarios.  
Click here to learn more about authorized payments: [[Authorized and recurring payments]]
Click here to learn more about token payments: [[Token_payment]]


|-
|-
Line 91: Line 102:
** "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, 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.
'''Note:''' this must be supplied as an array, because more funding source types are planned in the future.
|-
|-


| PaymentRequestId || string ||  
| PaymentRequestId || string ||  
* Optional
* Required
* Maximum length: 100 characters
* Maximum length: 100 characters
|| The unique identifier for the payment generated by the shop. This is optional, but highly recommended, 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.
|| 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.


|-
|-
Line 103: Line 116:
| PayerHint || string ||  
| PayerHint || string ||  
* Optional
* Optional
* If provided, must be valid email format
* Maximum length: 256 characters
* Maximum length: 256 characters
|| The shop can optionally 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. If provided, the Barion Smart Gateway automatically fills out the e-mail address field in the Barion wallet login form, speeding up the payment process.
|| The shop can optionally 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.


|-
|-


| RedirectUrl || string ||  
| RedirectUrl || string ||  
* Optional
* Required
* Maximum length: 2000 characters
* Maximum length: 2000 characters
|| The URL where the payer should be redirected after the payment is completed or cancelled. 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.
|| The URL where the payer should be redirected after the payment is completed or cancelled. 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.


|-
|-


| CallbackUrl || string ||  
| CallbackUrl || string ||  
* Optional
* Required
* Maximum length: 2000 characters
* Maximum length: 2000 characters
|| 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 <code>PaymentId</code> parameter. If not provided, the system will use the callback URL assigned to the shop that started the payment. Click here to learn more about the callback mechanism: [[Payment callback mechanism (IPN)]]
|| 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 <code>paymentId</code> parameter. Click here to learn more about the callback mechanism: [[Callback_mechanism|Payment callback mechanism (IPN)]]


|-
|-
Line 138: Line 152:
| ShippingAddress || [[ShippingAddress]] ||  
| ShippingAddress || [[ShippingAddress]] ||  
* Optional
* Optional
* Maximum length: 100 characters
|| 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.
|| 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 147: Line 160:
* Maximum length: 10 characters
* Maximum length: 10 characters
* Accepted values:  
* Accepted values:  
** "hu-HU" (Hungarian)
** "cs-CZ" (Czech)
** "de-DE" (German)
** "en-US" (English)
** "en-US" (English)
** "de-DE" (German)
** "es-ES" (Spanish)
** "fr-FR" (French)
** "fr-FR" (French)
** "es-ES" (Spanish)
** "hu-HU" (Hungarian)
** "sk-SK" (Slovakian)
** "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 161: Line 175:
* Required length: 3 characters
* Required length: 3 characters
* Accepted values:  
* Accepted values:  
** "HUF" (Hungarian Forint)
** "CZK" (Czech crown)
** "EUR" (Euro)
** "EUR" (Euro)
** "USD" (U.S. Dollar)
** "HUF" (Hungarian forint)
|| 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.
** "USD" (U.S. dollar)
|| 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. If no currency is provided, the default value is HUF. You must have a wallet in the given currency.
|-
 
| PayerPhoneNumber || string ||
* Optional
* Max length: 30 characters
* Expected format: 36701231234
* Required for using bank transfer payment
|| The phone number of the payer. Must be set to enable [[Bank_Transfer_Payment|bank transfer payment]].
|}
|}


Line 179: Line 202:
|-
|-


| Status || [[PaymentStatus]]|| The status of the payment in the Barion system. In a standard case this is <code>Prepared</code>. If the API call was sent using a previously authorized payment and the charge was successful,this is <code>Succeeded</code>.
| Status || [[PaymentStatus]]|| The status of the payment in the Barion system.  


|-
|-
Line 189: Line 212:
| 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.
| 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.


* If '''InitiateRecurrence''' was <code>true</code>, and a new authorized payment was successfully created, this will be <code>Successful</code> (if the payment could not be created, this will be <code>None</code>).
* 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 srouce, the result is <code>Failed</code>. If the given identifier is invalid or does not exist, the result is <code>NotFound</code>.
* 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>.


|-
|-

Latest revision as of 11:10, 1 February 2022

Barion API: Initialize a new payment

WARNING
The structure of this API call has been changed due to 3D Secure / PSD2 regulations! You can access the new structure here: Payment-Start-v2
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

Property name Property type Limitations and constraints Description
POSKey Guid
  • Required
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
  • Required
  • Accepted values:
    • "Immediate"
    • "Reservation"
    • "DelayedCapture"
The type of the payment, which can be either immediate, money reservation or delayed capture. 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

Click here to learn more about delayed capture payments: Delayed capture

ReservationPeriod TimeSpan (d.hh:mm:ss)
  • Required only if PaymentType is "Reservation"
  • Minimum value: one minute
  • Maximum value: one year
  • Default value: 30 minutes
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)
  • Required only if PaymentType is "DelayedCapture"
  • Minimum value: one minute
  • Maximum value: 21 days
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. The maximum time window depends on the country of the shop: 21 for Hungarian shops, 7 for everybody else
PaymentWindow TimeSpan (d.hh:mm:ss)
  • Optional
  • Minimum value: one minute
  • Maximum value: one week
  • Default value: 30 minutes
Time window for the payment to be completed by the payer. The payer must execute the payment before this elapses, or else the payment will expire and can no longer be completed.
GuestCheckOut bool
  • Required
  • Value must be "true" or "false", integer evaulation is not supported
Flag indicating wether 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
  • 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 susbscription payment scenarios.

Click here to learn more about token payments: Token_payment

RecurrenceId string
  • Required when executing authorized payments
  • Maximum length: 100 characters
  • Must be unique per shop and per user
A string used to identify a given authorized payment. Its purpose is determined by the value of the InitiateRecurrence property.
  • If InitiateRecurrence is true, this property must contain a new desired identifier for a new authorized 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 false, this property must contain an existing identifier for an authorized 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[]
  • Required
  • Accepted values:
    • "All"
    • "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.

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
  • Required
  • Maximum length: 100 characters
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
  • Optional
  • If provided, must be valid email format
  • Maximum length: 256 characters
The shop can optionally 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.
RedirectUrl string
  • Required
  • Maximum length: 2000 characters
The URL where the payer should be redirected after the payment is completed or cancelled. 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
  • Required
  • Maximum length: 2000 characters
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[]
  • Required
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
  • Optional
  • Maximum length: 100 characters
The order number generated by the shop. This is to aid the shop in identifying a given payment in their own system. This also shows up in generated monthly account statements and transaction history exports, so it also helps with bookkeeping.
ShippingAddress ShippingAddress
  • Optional
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
  • Required
  • Maximum length: 10 characters
  • Accepted values:
    • "cs-CZ" (Czech)
    • "de-DE" (German)
    • "en-US" (English)
    • "es-ES" (Spanish)
    • "fr-FR" (French)
    • "hu-HU" (Hungarian)
    • "sk-SK" (Slovak)
    • "sl-SI" (Slovenian)
This indicates in which language the Barion Smart Gateway should display for the payer upon redirect.
Currency string
  • Required
  • Required length: 3 characters
  • Accepted values:
    • "CZK" (Czech crown)
    • "EUR" (Euro)
    • "HUF" (Hungarian forint)
    • "USD" (U.S. dollar)
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. If no currency is provided, the default value is HUF. You must have a wallet in the given currency.
PayerPhoneNumber string
  • Optional
  • Max length: 30 characters
  • Expected format: 36701231234
  • Required for using bank transfer payment
The phone number of the payer. Must be set to enable bank transfer payment.

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.
  • If InitiateRecurrence was true, and a new authorized payment was successfully created, this will be None (because no actual token charge took place yet)
  • If InitiateRecurrence was false, 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 Successful. If the system could not charge the funding source, the result is Failed. If the given identifier is invalid or does not exist, the result is NotFound.
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.