1.4. Preauth Form, Capture and Cancel

Introduction

Preauthorization is a transaction type in which bank blocks the specified amount in the Payer’s card account and does not allow the cardholder to use this blocked money. It is important to know that the block remains for a definite period of time depending on whether this is a debit or a credit card (usually the maximum block period is 7 days for debit cards and 28 days for credit cards). Preauth Form integration allows Connecting Party to exclude itself from storing, processing, or transmitting Payer’s cardholder data or other sensitive payment details. Such data is submitted by Payer on GitPay hosted payment form in PCI DSS certified environment.
Capture is a transaction followed after preauth which deducts the locked amount from Payer’s card.
Cancel is opposite of Capture which cancels the deduction and returns locked amount back to Payer’s card.
All forms can be customized. Follow the Forms Customization reference to see examples and macros of Payment Page Customization, Prefilled Cardholder Data in Payment Page, Wait Page Customization and Finish Page Customization.

See terms definitions in Glossary.

Preauth Form Flow

  skinparam roundcorner 20
  skinparam sequenceArrowThickness 2
  skinparam ParticipantPadding 30
  actor Payer as Customer
  participant "Connecting Party\nwebsite" as Merchant
  participant "Payment Gateway" as g
  autonumber
  Customer -> Merchant: Checkout
  activate Merchant
  == Purchase payment request ==
  Merchant -> g: api/v2/preauth-form
  activate g
  g --> Merchant: Redirect-url, orderId
  deactivate g
  Merchant -> Customer: Provide redirect-url \nto payer’s browser
  deactivate Merchant
  activate Customer
  Customer -> g: GET redirect-url
  deactivate Customer
  activate g
  g --> Customer: Payment Form
  deactivate g
  activate Customer
  Customer -> g: Submit form
  deactivate Customer
  activate g
  g --> g: Process payment
  == Final redirect of customer ==
  g -> Customer: Connecting Party website redirect_url
  activate Customer
  Customer -> Merchant: POST redirect_url\nstatus, orderid
  deactivate Customer
  activate Merchant
  group Get Final Status
  == Receive Connecting Party Callback ==
  Merchant <- g: Сallback with final status
  g <-- Merchant: HTTP 200
  deactivate g
  == Order Status Request ==
  Merchant -> g: api/v2/status
  activate g
  g --> Merchant: Response \nstatus, order-stage
  deactivate g
  end
  Merchant -> Customer: Show result
  deactivate Merchant

(2) To implement preauth-form request see /api/v2/preauth-form/.
(9) To implement final redirect see Final Redirect.
(11,12) To implement order status request see /api/v2/status/. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
(13) To implement callback with final status handling see Connecting Party.

Capture Flow

  skinparam roundcorner 20
  skinparam sequenceArrowThickness 1
  skinparam maxmessagesize 100
  skinparam sequenceParticipant underline
  actor Payer
  participant "Connecting party" as A
  participant "Payment Gateway" as B
  hnote over A,B : Successful Preauth Transaction
  autonumber
  group Optional
  Payer -> A: Initiate Capture
  activate A
  end
  == Capture ==
  A -> B: api/v2/capture
  activate B
  B --> A: Order ID
  B -> B: Process Capture
  group Get Final Status
  == Receive Connecting Party Callback ==
  A <- B: Callback with Final Status
  A --> B: HTTP 200
  deactivate B
  == Order Status Request ==
  A -> B: Get Status by Order ID api/v2/status
  activate B
  B --> A: Response with Status, Order-stage
  deactivate B
  end
  group Optional
  A --> Payer: Final Status
  deactivate A
  end

(1) Capture can be initiated by Connecting Party based on internal business model or Payer’s request.
(2) To implement capture request see /api/v2/capture/.
(5) Callback for Capture will be sent only if notify_url was provided in initial transaction request or additional callback URL for Capture transactions is specified on the endpoint level. If server_callback_url was provided in initial transaction request, callback for Capture will not be sent. To implement callback with final status handling see Connecting Party Callbacks.
(7) To implement order status request see /api/v2/status/. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
(9) Final Status can be sent by Connecting Party based on internal business model or by Payer’s request.

Cancel Flow

  skinparam roundcorner 20
  skinparam sequenceArrowThickness 1
  skinparam maxmessagesize 100
  skinparam sequenceParticipant underline
  actor Payer
  participant "Connecting party" as A
  participant "Payment Gateway" as B
  hnote over A,B : Successful Preauth Transaction
  autonumber
  group Optional
  Payer -> A: Initiate Cancel
  activate A
  end
  == Cancel ==
  A -> B: api/v2/return
  activate B
  B --> A: Order ID
  B -> B: Process Cancel
  group Get Final Status
  == Receive Connecting Party Callback ==
  A <- B: Callback with Final Status
  A --> B: HTTP 200
  deactivate B
  == Order Status Request ==
  A -> B: Get Status by Order ID api/v2/status
  activate B
  B --> A: Response with Status, Order-stage
  deactivate B
  end
  group Optional
  A --> Payer: Final Status
  deactivate A
  end

(1) Cancel can be initiated by Connecting Party based on internal business model or Payer’s request.
(2) To implement cancel request see /api/v2/return/.
(5) Callback for Cancel will be sent only if notify_url was provided in initial transaction request or additional callback URL for Cancel transactions is specified on the endpoint level. If server_callback_url was provided in initial transaction request, callback for Cancel will not be sent. To implement callback with final status handling see Connecting Party Callbacks.
(7) To implement order status request see /api/v2/status/. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
(9) Final Status can be sent by Connecting Party based on internal business model or by Payer’s request.