ApplePay-StartPaymentWithAppleToken: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
VisualWikitext
 
(11 intermediate revisions by one other user not shown)
Line 9: Line 9:


== Input properties ==
== Input properties ==


{|
{|
Line 16: Line 15:
| 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.
| 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.
|-
|-
| ShippingContact || [[ApplePayShippingContact|ShippingContact]] || * Required ||
| ShippingContact || [[ApplePayShippingContact|ShippingContact]] || * Required || The shipping information of the payer provided by Apple
|-
| BillingContact || [[ApplePayBillingContact|BillingContact]] || * Required|| The billing information of the payer provided by Apple
|-
| ApplePayToken || [[ApplePayToken|Token]] || * Required|| The Token provided by Apple in [https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778020-onpaymentauthorized onpaymentauthorized] callback.
|-
| PaymentType || string ||
* Required
* Accepted values:
** "Immediate"
** "Reservation"
** "DelayedCapture"
|| 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]], and delayed capture: [[Delayed_Capture|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: 7 days (21 days in case of a Hungarian shop)
* Default value: seven 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.
 
|-
| 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.
|-
| 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 <code>paymentId</code> parameter. Click here to learn more about the callback mechanism: [[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 its own system. This also shows up in generated monthly account statements and transaction history exports, so it also helps with bookkeeping.
 
|-
| Currency || string ||
* Required
* 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.
|-
|}
Note: You can pass all the properties of [[Payment-Start-v2|PaymentStart]], but the rest of it is not used in this process, thus unnecessary.
 
== Output properties ==
No specific output property is available, besided the generic ones.
 
== Possible error responses  ==
 
{| class="wikitable api-table"
! Error code || Description
|-
| AuthenticationFailed|| Authentication failed.
|-
| ModelValidationError || This happens when some of the input properties fail the basic validation. For example the session request url is malformed.
|-
| InvalidApplePayToken|| The provided token is invalid.
|-
| InvalidApplePayMessage|| The provided message is invalid.
|-
| ApplePayNotAllowed|| Apple Pay not allowed for token payments.
|-
|-
| BillingContact || [[ApplePayBillingContact|BillingContact]] || * Required||
| NotRegisteredToApple|| The provided shop url is not registered to Apple.
|-
|-
| Token || [[ApplePayToken|ApplePayToken]] || * Required||
|}
|}

Latest revision as of 15:43, 2 February 2022

Barion API: Start Payment With Apple token

POST /v2/ApplePay/StartPaymentWithAppleToken

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.
ShippingContact ShippingContact * Required The shipping information of the payer provided by Apple
BillingContact BillingContact * Required The billing information of the payer provided by Apple
ApplePayToken Token * Required The Token provided by Apple in onpaymentauthorized callback.
PaymentType string
  • Required
  • Accepted values:
    • "Immediate"
    • "Reservation"
    • "DelayedCapture"
 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)
  • 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: 7 days (21 days in case of a Hungarian shop)
  • Default value: seven 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.
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.
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 its own system. This also shows up in generated monthly account statements and transaction history exports, so it also helps with bookkeeping.
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.

Note: You can pass all the properties of PaymentStart, but the rest of it is not used in this process, thus unnecessary.

Output properties

No specific output property is available, besided the generic ones.

Possible error responses

Error code Description
AuthenticationFailed Authentication failed.
ModelValidationError This happens when some of the input properties fail the basic validation. For example the session request url is malformed.
InvalidApplePayToken The provided token is invalid.
InvalidApplePayMessage The provided message is invalid.
ApplePayNotAllowed Apple Pay not allowed for token payments.
NotRegisteredToApple The provided shop url is not registered to Apple.
Retrieved from "https://docs.barion.com/index.php?title=ApplePay-StartPaymentWithAppleToken&oldid=3321"