Pay by Bank Integration Developer Guide {#paybybank-about-guide} ================================================================ This section describes how to use this guide and where to find further information. Audience and Purpose : This guide is written for merchants who want to offer Pay by Bank services to customers. It describes tasks that a merchant must complete in order to make a payment, request the status of a payment, or refund a payment. It is intended to help the merchant provide a seamless customer payment experience. Conventions : This statement appears in this document: > IMPORTANT > An *Important* statement contains information essential to successfully completing a task or learning a concept. Related Documentation : Visit the [`Cybersource` documentation hub](https://developer.cybersource.com/docs.md "") to find additional technical documentation. Customer Support : For support information about any service, visit the Support Center: Recent Revisions to This Document {#paybybank-doc-revisions} ============================================================ 25.11.01 -------- Added REST examples for sale, refund, and check status services. 24.02 ----- Updated the possible webhook notification response statuses. See [Webhook Subscriptions](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-webhook-intro.md ""). 24.01 ----- Initial release. Introduction to Pay by Bank {#paybybank-intro} ============================================== Pay by Bank is a solution that enables you to offer your e-commerce customers the ability to pay directly from their bank account in real time without providing payment card information. When a payment is processed, your customer's bank transfers the funds directly to your merchant bank account. In the UK, Pay by Bank follows the open banking regulations for bank-to-bank transfers. Benefits of Using Pay by Bank ----------------------------- Pay by Bank makes processing e-commerce transactions simpler, faster, and more secure by: * Reducing customer data storage because card data is no longer needed. * Streamlining reconciliation data into an easy-to-read report. * Using a customer's bank authentication network to securely process payments. * Avoiding card processing fees. * Providing an easy connection to Pay by Bank through an API integration. Supported Services ------------------ Sale, refund, and check status services are available with Pay by Bank. For more information, see these sections: * [Sale](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-sale-intro.md "") * [Refund](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-refund-intro.md "") * [Check Status](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-status-intro.md "") You can also subscribe to webhook notifications. With webhook subscriptions, `Cybersource` automatically notifies you when a sale or a refund is complete. See [Webhook Subscriptions](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-webhook-intro.md ""). Requirements ------------ You must have a merchant ID for each country in which you process transactions. Contact your `Cybersource` account manager for more information. Supported Currencies -------------------- This table lists the currencies supported by the Pay by Bank services. | Currency | Currency Code | |------------------------|---------------| | British pound sterling | `GBP` | | Euro | `EUR`\* | [Supported Currencies] \*Refunds are not currently supported for EUR. Payment Workflow {#paybybank-intro-flow} ======================================== This workflow describes the sequence of events that comprises a successful Pay by Bank payment. #### Figure: Processing Payment Workflow ![](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/altpay/pay-by-bank/graphics/paybybank-flow-sale.svg/jcr:content/renditions/original) 1. The customer chooses the Pay by Bank payment option and their bank while checking out on the merchant's website. 2. The merchant sends `Cybersource` a sale API request. For more information, see [Sale](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-sale-intro.md ""). 3. `Cybersource` responds to the merchant with a `PENDING` status and a redirect URL. 4. The merchant redirects the customer to the URL. 5. The customer completes checkout using their account credentials and is then redirected to the merchant website. 6. `Cybersource` sends a `SETTLED` sale status webhook notification to the merchant. 7. The merchant displays a payment completion confirmation to the customer. 8. To check the status of a sale, the merchant sends a check status API request if they did not receive a webhook notification. For more information, see [Check Status](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-status-intro.md ""). 9. `Cybersource` sends the merchant one of these statuses: * `ABANDONED`: The customer did not complete checkout within the allotted time, and the redirect URL has expired. * `PENDING`: The customer did not complete checkout. * `SETTLED`: The sale request is settled for the requested amount. 10. The merchant confirms the completed checkout to the customer when the sale status updates to `SETTLED`. Refund Workflow {#paybybank-intro-flow-refund} ============================================== This workflow describes the sequence of events that comprises a successful Pay by Bank refund. #### Figure: Issuing a Refund Workflow ![](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/altpay/pay-by-bank/graphics/paybybank-flow-refund.svg/jcr:content/renditions/original) 1. The customer returns a purchased item to the merchant. 2. The merchant issues a refund in one of two ways: * By sending a refund API request to `Cybersource`. For more information, see [Refund](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-refund-intro.md ""). * By using the `Business Center` to issue a refund. 3. `Cybersource` sends a response status in one of two ways: * By sending a `PENDING` response status if the merchant sent a refund API request. * By displaying a pending refund in the `Business Center` if the merchant used the `Business Center` to issue the refund. 4. `Cybersource` sends an updated status when the refund has completed processing in one of two ways: * Sending a `REFUNDED` webhook notification if the merchant sent a refund API request. * Displaying a completed refund if the merchant used the `Business Center` to issue the refund. 5. The merchant displays a confirmation of the refund to the customer. 6. To check the status of a refund, the merchant sends a check status API request if they did not receive either a webhook notification or an updated status in the `Business Center`. For more information, see [Check Status](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-status-intro.md ""). 7. `Cybersource` responds with one of these statuses: * `FAILED`: The refund request failed. A failed request can be due to Pay by Bank rejecting the transaction or due to a technical error. * `PENDING`: The refund request is accepted but is not completed. Request the check status service to retrieve status updates. * `REFUNDED`: The refund amount is successfully refunded. 8. The merchant confirms the completed refund to the customer when the status updates to `REFUNDED`. Transaction Statuses Workflow {#pay-by-bank-intro-status-flow} ============================================================== This workflow describes the sequence of possible statuses you can receive when processing a Pay by Bank transaction. #### Figure: Transaction Statuses Workflow ![](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/altpay/pay-by-bank/graphics/paybybank-flow-status.svg/jcr:content/renditions/original) 1. The merchant sends a sale API request to `Cybersource` and receives one of these possible statuses: * `PENDING`: The sale request is accepted but the customer has not completed checkout. A webhook notification informs you when the customer completes checking out and the sale settles. See [Webhook Subscriptions](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-webhook-intro.md ""). If you do not receive a webhook notification, send a check status request. See [Check Status](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-status-intro.md ""). * `REJECT`: The sale is not successful. Send a new sale request. 2. The merchant sends a check status API request to `Cybersource` to verify the status of the sale and receives one of these statuses: * `ABANDONED`: The customer did not complete checkout before the redirect URL expired. * `COMPLETED`: The customer completed the checkout process and the sale is currently under review. You can send the check status request in 60-minute intervals to retrieve the current status. * `PENDING`: The sale request is accepted but is not complete. You can send the check status request in 60-minute intervals until the status updates. * `REJECT`: The sale request is not successful. An unsuccessful request can be due to either Pay by Bank rejecting the transaction or a technical error. * `SETTLED`: The sale is complete for the requested amount. 3. If the customer decides to return the purchase, the merchant sends a refund API request to `Cybersource` and receives one of these statuses: * `PENDING`: The refund request is accepted and is processing. A webhook notification informs you when the refund is complete. See [Webhook Subscriptions](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-webhook-intro.md ""). If you do not receive a webhook notification, send a check status request. See [Check Status](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-status-intro.md ""). * `REJECT`: The refund request is not successful. Send a new refund request. 4. The merchant sends a check status API request to `Cybersource` to verify the refund status and receives one of these statuses: * `PENDING`: The refund request is accepted but is not complete. Continue to request the check status service in 60-minute intervals until the status updates. * `REFUNDED`: The settled amount is successfully refunded back to the customer's account. * `REJECT`: The refund request is not successful. An unsuccessful request can be due to either Pay by Bank rejecting the transaction or a technical error. Pay by Bank Services {#paybybank-intro-services} ================================================ This section describes how to successfully request the sale, refund, and check status services. You can also subscribe to receive webhook notifications to know when a sale or refund status updates. For more information, see [Webhook Subscriptions](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-webhook-intro.md ""). Sale {#paybybank-sale-intro} ============================ Send a sale request to begin processing a payment. A response to a successful request includes a `PENDING` status and a URL in the processorInformation.paymentURL field. Redirect the customer to the URL to allow the customer to complete the payment on their bank's website. After sending a successful request, you can send a follow-on check status request or a refund request. These follow-on services require the request ID from the sale response, which is the id field value. Pay by Bank requires that you include line items in your sale request. [Line items](# "") are used to include information about the goods and services that your customers purchase, such as product name, quantity, and price. Endpoints --------- **Production:** `POST ``https://api.cybersource.com``/pts/v2/payments`{#paybybank-sale-intro_d17e345} **Test:** `POST ``https://apitest.cybersource.com``/pts/v2/payments`{#paybybank-sale-intro_d17e355} Response Statuses {#paybybank-sale-intro_status-response} --------------------------------------------------------- `Cybersource` responds to your sale request with one of these statuses in the status field: * `PENDING`: The sale request is accepted but the customer has not completed checkout. A webhook notification informs you when the customer completes checking out and the sale settles. See [Webhook Subscriptions](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-webhook-intro.md ""). If you do not receive a webhook notification, send a check status request. See [Check Status](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-status-intro.md ""). * `REJECT`: The sale is not successful. Send a new sale request. {#paybybank-sale-intro_statuses-sale} `Cybersource` also responds with a reason code in the processorInformation.responseCode field. For more information about reason codes, see [Reason Codes and Pay by Bank Response Codes](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-reference-codes.md ""). If you send a check status request to retrieve the current sale status, these are the possible responses: * `ABANDONED`: The customer did not complete checkout before the redirect URL expired. * `COMPLETED`: The customer completed the checkout process and the sale is currently under review. You can send the check status request in 60-minute intervals to retrieve the current status. * `PENDING`: The sale request is accepted but is not complete. You can send the check status request in 60-minute intervals until the status updates. * `REJECT`: The sale request is not successful. An unsuccessful request can be due to either Pay by Bank rejecting the transaction or a technical error. * `SETTLED`: The sale is complete for the requested amount. {#paybybank-sale-intro_statuses-sale-check} Processing a Sale {#paybybank-sale-req-fields-rest} =================================================== You redirect the customer to a website in order to complete the checkout. Follow these steps to process a sale. 1. Send a `POST` request to the `https://api.cybersource.com``/pts/v2/payments`{#paybybank-sale-req-fields-rest_sale-test-rest} endpoint and include these required fields: #### ADDITIONAL INFORMATION clientReferenceInformation.code : merchantInformation.merchantDescriptor.name : orderInformation.amountDetails.currency : Set to `GBP`. orderInformation.amountDetails.totalAmount : orderInformation.billTo.email : orderInformation.billTo.firstName : orderInformation.billTo.lastName : orderInformation.lineItems.productName : orderInformation.lineItems.quantity : orderInformation.lineItems.totalAmount : orderInformation.lineItems.unitPrice : paymentInformation.paymentType.method.name : Set to `bofaPayByBank`. paymentInformation.paymentType.name : Set to `bankTransfer`. processingInformation.actionList : Set to `AP_SALE`. {#paybybank-sale-req-fields-rest_dl_nsd_xys_fgc} 2. If needed, include any of these optional line item fields in the request: #### ADDITIONAL INFORMATION merchantInformation.merchantDescriptor.administrativeArea : merchantInformation.merchantDescriptor.country : orderInformation.amountDetails.discountAmount : orderInformation.amountDetails.dutyAmount : orderInformation.amountDetails.exchangeRate : orderInformation.amountDetails.taxAmount : orderInformation.billTo.address1 : orderInformation.billTo.address2 : orderInformation.billTo.administrativeArea : orderInformation.billTo.company.name : orderInformation.billTo.country : orderInformation.billTo.county : orderInformation.billTo.district : orderInformation.billTo.locality : orderInformation.billTo.middleName : orderInformation.billTo.phoneNumber : orderInformation.billTo.postalCode : orderInformation.billTo.title : orderInformation.invoiceDetails.productDescription : orderInformation.lineItems.discountAmount : orderInformation.lineItems.discountRate : orderInformation.lineItems.taxAmount : orderInformation.lineItems.taxRate : orderInformation.shippingDetails.shippingMethod : orderInformation.shipTo.address1 : orderInformation.shipTo.address2 : orderInformation.shipTo.administrativeArea : orderInformation.shipTo.company : orderInformation.shipTo.country : orderInformation.shipTo.county : orderInformation.shipTo.district : orderInformation.shipTo.email : orderInformation.shipTo.firstName : orderInformation.shipTo.lastName : orderInformation.shipTo.locality : orderInformation.shipTo.middleName : orderInformation.shipTo.phoneNumber : orderInformation.shipTo.postalCode : {#paybybank-sale-req-fields-rest_dl_k3f_h1t_fgc} 3. Direct the customer to the URL in the processorInformation.paymentURL response field. #### ADDITIONAL INFORMATION ``` "paymentUrl": "https://checkout.b.banked.com/eu/527057ed-d48c-4333-a252-03c36d2132db?token=eyJhbGciOiJIUz" ``` 4. When the customer validates the purchase on their bank's website, they are redirected to the merchant's website that you provided in the processorInformation.completeUrl request field. #### ADDITIONAL INFORMATION ``` "completeUrl": "https://www.merchant.redirect.url.from.request.html?actionsuccess" ``` #### AFTER COMPLETING THE TASK When the sale amount is successfully processed, `Cybersource` sends a `SETTLED` webhook notification. See [Webhook Subscriptions](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-webhook-intro.md ""). If you do not receive a webhook notification, send a check status request. See [Check Status](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-status-intro.md ""). `REST` Example: Processing a Sale {#paybybank-sale-ex-rest} =========================================================== Request ``` { "clientReferenceInformation": { "code": "TC84100-1" }, "processingInformation": { "actionList": [ "AP_SALE" ] }, "orderInformation": { "lineItems": [ { "unitPrice": "14.16", "totalAmount": "70.80", "quantity": 5, "productName": "Skirt on the sky" } ], "billTo": { "lastName": "Bowditch", "firstName": "Comet", "email": "srbuyeroffice@cybs.com" }, "amountDetails": { "totalAmount": "1999.99", "currency": "GBP" } }, "merchantInformation": { "merchantDescriptor": { "name": "BofA Merchant" } }, "paymentInformation": { "paymentType": { "name": "bankTransfer", "method": { "name": "bofaPayByBank" } } } } ``` Response to a Successful Request ``` { "orderInformation": { "amountDetails": { "totalAmount": "70.80", "currency": "GBP" } }, "processorInformation": { "transactionId": "527057ed-d48c-4333-a252-03c36d2132db", "paymentUrl": "https://checkout.b.banked.com/eu/527057ed-d48c-4333-a252-03c36d2132db?token=eyJhbGciOiJIUz", "responseCode": "00001", "completeUrl": "https://www.merchant.redirect.url.from.request.html?actionsuccess" }, "message": "Request was processed successfully.", "clientReferenceInformation": { "code": "TC84100-1" }, "reconciliationId": "KOZX0DMQKX17", "status": "PENDING", "id": "7545074870976150504806", "submitTimeUtc": "2025-08-06T19:11:27Z" } ``` Refund {#paybybank-refund-intro} ================================ Send a refund request to issue a full or partial refund to the customer's bank account. Refunds can be requested only when the sale is settled. A refund request requires the request ID from the sale response. > IMPORTANT You can only refund payments processed with GBP currency. Endpoints --------- **Production:** `POST ``https://api.cybersource.com``/pts/v2/payments/`*{id}*`/refunds`{#paybybank-refund-intro_d17e372} **Test:** `POST ``https://apitest.cybersource.com``/pts/v2/payments/`*{id}*`/refunds`{#paybybank-refund-intro_d17e385} The *{id}* is the request ID contained in the original transaction request. Response Statuses ----------------- `Cybersource` responds to your refund request with one of these statuses in the status field: * `PENDING`: The refund request is accepted and is processing. A webhook notification informs you when the refund is complete. See [Webhook Subscriptions](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-webhook-intro.md ""). If you do not receive a webhook notification, send a check status request. See [Check Status](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-status-intro.md ""). * `REJECT`: The refund request is not successful. Send a new refund request. {#paybybank-refund-intro_status-refund} `Cybersource` also responds with a reason code in the processorInformation.responseCode field. For more information about reason codes, see [Reason Codes and Pay by Bank Response Codes](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-reference-codes.md ""). If you send a check status request to retrieve the current refund status, these are the possible responses: * `PENDING`: The refund request is accepted but is not complete. Continue to request the check status service in 60-minute intervals until the status updates. * `REFUNDED`: The settled amount is successfully refunded back to the customer's account. * `REJECT`: The refund request is not successful. An unsuccessful request can be due to either Pay by Bank rejecting the transaction or a technical error. {#paybybank-refund-intro_status-refund-check} Required Fields for Processing a Refund {#paybybank-refund-req-fields} ====================================================================== clientReferenceInformation.code : orderInformation.amountDetails.currency : Set to `GBP`. orderInformation.amountDetails.totalAmount : paymentInformation.paymentType.method.name : Set to `bofaPayByBank`. paymentInformation.paymentType.name : Set to `bankTransfer`. processingInformation.actionList : Set to `AP_REFUND`. {#paybybank-refund-req-fields_dl_gk2_4ft_fgc} `REST` Example: Issuing a Refund {#paybybank-refund-ex-rest} ============================================================ Request ``` { "clientReferenceInformation": { "code": "TC84100-1" }, "paymentInformation": { "paymentType": { "name": "bankTransfer", "method": { "name": "bofaPayByBank" } } }, "processingInformation": { "actionList": ["AP_REFUND"] }, "orderInformation": { "amountDetails": { "totalAmount": "1999.00", "currency": "GBP" } } } ``` Response to a Successful Request ``` { "processorInformation": { "responseCode": "00001", "transactionId": "1a043850-322b-2e06-334e-0c4b0c41083f" }, "orderInformation": { "amountDetails": { "totalAmount": "1999.00", "currency": "LOgGSXjNbVmXgvrhXlFMaablr" } }, "clientReferenceInformation": { "code": "TC84100-1" }, "reconciliationId": "KOZX0DMQKX18", "message": "Request was processed successfully.", "status": "PENDING", "id": "7545091091436400404807", "submitTimeUtc": "2025-08-06T19:38:29Z" } ``` Check Status {#paybybank-status-intro} ====================================== Send a check status request to retrieve status updates for either a pending sale or refund. A check status request requires the request ID from the sale response or the refund response, which is the id field value. `Cybersource` recommends using the check status service only when you do not receive a webhook notification. To set up a webhook subscription, see [Webhook Subscriptions](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-intro-services/paybybank-webhook-intro.md ""). Endpoints --------- **Production:** `POST ``https://api.cybersource.com``/pts/v2/refresh-payment-status/`*{id}*{#paybybank-status-intro_d17e193} **Test:** `POST ``https://apitest.cybersource.com``/pts/v2/refresh-payment-status/`*{id}*{#paybybank-status-intro_d17e205} Set the *`{id}`* to the request ID of the API service you are retrieving. Response Statuses {#paybybank-status-intro_section_jgq_qxp_jdc} --------------------------------------------------------------- `Cybersource` responds to your check sale status request with one of these statuses in the status field: Check Status for a Sale : * `ABANDONED`: The customer did not complete checkout within the allotted time, and the redirect URL has expired. * `COMPLETED`: The customer completed the checkout process. * `PENDING`: The sale request is accepted but is not complete. Request the check status service to retrieve status updates. * `REJECT`: The sale request failed. A failed request can be due to either Pay by Bank rejecting the transaction or due to a technical error. * `SETTLED`: The sale request is settled for the requested amount. Check Status for a Refund : * `PENDING`: The refund request is accepted but is not complete. Request the check status service to retrieve status updates. * `REFUNDED`: The settled amount is successfully refunded. * `REJECT`: The refund request failed. A failed request can be due to either Pay by Bank rejecting the transaction or due to a technical error. The check status service also responds with a reason code in the processorInformation.responseCode field. For more information about reason codes, see [Reason Codes and Pay by Bank Response Codes](/docs/cybs/en-us/pay-by-bank/developer/all/rest/pay-by-bank/paybybank-reference-codes.md ""). Required Fields for a Check Status Request {#paybybank-status-req-fields} ========================================================================= clientReferenceInformation.code : paymentInformation.paymentType.method.name : Set to `bofaPayByBank`. paymentInformation.paymentType.name : Set to `bankTransfer`. processingInformation.actionList : Set to `AP_STATUS`. {#paybybank-status-req-fields_dl_ztt_4ft_fgc} `REST` Example: Requesting a Check Status {#paybybank-status-ex-rest} ===================================================================== Request ``` { "clientReferenceInformation": { "code": "TC84100-1" }, "paymentInformation": { "paymentType": { "name": "bankTransfer", "method": { "name": "bofaPayByBank" } } }, "processingInformation": { "actionList": ["AP_STATUS"] } } ``` Response to a Successful Request ``` { "processorInformation": { "responseCode": "00004" }, "clientReferenceInformation": { "code": "TC84100-1" }, "reconciliationId": "KPEPKDMPHGA3", "message": "Request was processed successfully.", "status": "SETTLED", "id": "7545090267166390604807", "submitTimeUtc": "2025-08-06T19:37:06Z" } ``` Webhook Subscriptions {#paybybank-webhook-intro} ================================================ Webhooks are automated notifications generated by system events that occur in your organization. You can enroll in a sale or refund event and designate a URL to receive notifications when the event updates. You set up your webhook subscriptions only once. Notifications that contain sensitive, personally identifiable information such as account numbers are sent using message-level encryption. Transport Layer Security is required in order to ensure data integrity. Endpoints --------- * **Production** : `https://api.cybersource.com``/notification-subscriptions/v2/webhooks` * **Test** : `https://apitest.cybersource.com``/notification-subscriptions/v1/webhooks` Notification Statuses --------------------- Webhook subscriptions send these status notifications: * `ABANDONED`: The customer did not complete the transaction. * `CANCELLED`: The customer did not complete the checkout using the redirect URL. * `COMPLETED`: The transaction is complete. * `FAILED`: The payment failed. * `PENDING`: The payment was initiated. * `REFUNDED`: The settled amount is successfully refunded. * `SETTLED`: The sale request is settled for the requested amount. {#paybybank-webhook-intro_ul_ptj_5xs_n5b} Additional Requirements ----------------------- Webhooks Implementation Guide : There are additional requirements for implementing webhooks that are not discussed in this guide. For more information, see the *[Webhooks Implementation Guide](https://developer.cybersource.com/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-intro.md "")* for the REST API. Create New Webhooks : To create an alternative payment notification webhook, see the [Create a Webhook](https://developer.cybersource.com/api-reference-assets/index.md?stage=pilot#webhooks_create-new-webhooks_create-a-webhook "") section in the *`Cybersource` REST API Reference*. Required Fields for Subscribing to a Webhook {#paybybank-webhook-req-fields} ============================================================================ healthCheckUrl : organizationId : products.eventTypes : Set to `payments.payments.updated`. products.productId : Set to `alternativePaymentMethods`. webhookUrl : `REST` Example: Subscribing to a Webhook {#paybybank-webhook-ex-so} =================================================================== There are additional requirements for implementing webhooks that are not discussed in this guide. For more information, see the *[Webhooks Implementation Guide](https://developer.cybersource.com/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-intro.md "")* for the REST API. Request ``` {​​​ "name": "My Custom Webhook", "description": "Sample Webhook from Developer Center", "organizationId": "organizationId", "productId": "alternativePaymentMethods", "eventTypes": [ "payments.payments.updated" ], "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient", "healthCheckUrl": "https://MyWebhookServer.com:8443/simulateClientHealthCheck", "notificationScope": "SELF", "retryPolicy": {​​​​​​​​​​ "algorithm": "ARITHMETIC", "firstRetry": 1, "interval": 1, "numberOfRetries": 3, "deactivateFlag": "false", "repeatSequenceCount": 0, "repeatSequenceWaitTime": 0 }​​​​​​​​​​, "securityPolicy": {​​​​​​​​​​ "securityType": "KEY", "proxyType": "external" }​​​​​​​​​​ }​​​​​​​​​​ ``` Encrypted Response to Successful Request ``` {​​ "eventType": "payments.payments.updated", "productId": "alternativePaymentMethods", "organizationId": "organizationId", "transactionTraceId": "6584251287300178228949", "payload": "{​​​​​​​​​CBC}​​​​​​​​​​​​​​​​nL1LK67IH1LQKad3qyhilPoeDGrHo/6ClIZ17HSC5YX9TQFIgCOhVPi139kmB/xiVCALGdU8YjqmOEwo3iUXKy6oq517eDiTHv/Crq0pOiEzs0dtuTvYhriXrpvQCF+XxqfqTPPFyus/10/FlyEK7ZKIc66DrmA3IfdlYTpL7gICAOttQrMWNGODFu7JXaFyQahDarhFCPsvWMwyRK9yOLwihWj3lC1yPD/1xA7xpTGp9kX3ABKzzZxKjHoC5OYOhSLQm7MPnN4BND+Hs+cU/mYzLYxfN7GSDSbqZwhbJgXaKapT8lMeXUTlPejyqGyCPagWNqZJFHx6q1OBJKB8XZ0pZIpT+v+bMe5EnbQyv9Nj6BJX1BBgqhvKmXrSqD16", "metadata": {​​​​​​​​​​​​​​​​ "notificationTypeID": "5", "notificationReason": "payment" }​​​​​​​​​​​​​​​​ }​​​​​​​​​​​​​​​​ ``` Decrypted Response to Successful Request ``` {​​​​​​​​​​​​​​​​ "id": "6584251287300178228949", "reconcillationID": "85100194sale", "status": "settled", "submitTimeUTC": "2022-07-21T17:38:48Z", "clientReferenceInformation.code": "TC85100-1", "orderInformation.amountDetails.totalAmount": "1999.99", "orderInformation.amountDetails.currency": "GBP" }​​​​​​​​​​​​​​​​ ``` Including Line Items in Requests {#paypal-create-order-line-items} ================================================================== Unique items in your customers' purchases can be itemized as line items when you create or manage an order. *Line items* are used to include information about each item, such as product name, quantity, and price. Line items are included in a request in the lineItem\[\] array request field. These fields are required for each line item in your request: [orderInformation.lineItems\[\].productDescription](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-line-items-product-description.md "") : [orderInformation.lineItems\[\].productName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-line-items-product-name.md "") : [orderInformation.lineItems\[\].quantity](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-line-items-quantity.md "") : [orderInformation.lineItems\[\].taxAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-line-items-tax-amount-request.md "") : [orderInformation.lineItems\[\].totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-line-items-total-amount.md "") : [orderInformation.lineItems\[\].typeOfSupply](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-line-items-type-of-supply.md "") : [orderInformation.lineItems\[\].unitPrice](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-line-items-unit-price.md "") : Including Line Items This example shows how to format line items in a request. ``` { "orderInformation": { "lineItems": [ { "productName": "test-product-1", "quantity": 5, "productDescription": "description-123", "unitPrice": "20", "taxAmount": "10", "totalAmount": "100", "typeOfSupply": "01" }, { "productName": "test-product-2", "quantity": 1, "productDescription": "description-456", "unitPrice": "5", "taxAmount": "1", "totalAmount": "6", "typeOfSupply": "01" }, { "productName": "test-product-3", "quantity": 2, "productDescription": "description-789", "unitPrice": "4", "taxAmount": "2", "totalAmount": "10", "typeOfSupply": "01" } ] } } ``` Reason Codes and Pay by Bank Response Codes {#paybybank-reference-codes} ======================================================================== This table describes some of the reason codes and Pay by Bank response codes that you receive when you request a Pay by Bank service. Use the values listed in the table to determine the transaction result. For additional reason codes and descriptions, see the [*`Cybersource` Reason Codes with REST API response* article](https://support.visaacceptance.com/knowledgebase/knowledgearticle/?code=KA-04103 "") in the `Cybersource` Developer Center. | Reason Code | Pay by Bank Response Code | Description | |-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `100` | * `00000`: Completed status * `00001`: Pending status * `00002`: Abandoned status * `00003`: Authorized status * `00004`: Settled status * `00006`: Refunded status {#paybybank-reference-codes_ul_dtk_zxx_yxb} | Successful transaction. | | `102` | * `10000`: Failed status | One or more fields in the request contain invalid data. | | `150` | * `20000`: Failed status * `20001`: Failed status * `20002`: Failed status {#paybybank-reference-codes_ul_qqc_3yx_yxb} | Possible reasons: * The signature was not included in the HTTP header. * The signature in the HTTP header has expired, or it is not a valid signature. {#paybybank-reference-codes_ul_obp_kyx_yxb} | | `203` | * `30000`: Failed status * `30100`: Failed status * `30200`: Failed status * `30400`: Failed status * `30500`: Failed status {#paybybank-reference-codes_ul_lvp_pyx_yxb} | Pay by Bank declined the transaction because of funding source problems, or the transaction was flagged as high risk. | | `204` | * `30350`: Failed status | Payment declined because of insufficient funds in the account. | | `233` | * `30600`: Failed status * `30700`: Failed status | Pay by Bank declined the transaction because of tax errors or government compliance errors. | [Reason Codes and Pay by Bank Response Codes] Generating Reports In the `Business Center` {#conref-altpay-reporting} ====================================================================== You can generate various types of reports for your financial and reconciliation data. For more information about how to automate your reports, see the [*Reporting Developer Guide*](https://developer.cybersource.com/docs/cybs/en-us/reporting/developer/all/rest/reporting/reporting_api.md ""). For more information about how to use your `Business Center` account to generate reports, see the [*Reporting User Guide*](https://developer.cybersource.com/library/documentation/dev_guides/reporting_and_reconciliation/Reporting_User.pdf ""). The Reporting User Guide contains these relevant topics: * How and When Reports Are Generated * Downloading Available Reports * Subscribing to Standard Reports Additional Resources -------------------- For additional information about how to use the `Business Center` and manage reports, see these helpful resources. `Business Center` Navigation : For an overview of the various resources available in the `Business Center`, see this YouTube video: [watch?v=UDmAWGHPbWs](https://www.youtube.com/watch?v=UDmAWGHPbWs "") Getting Started with the `Business Center` : For a step-by-step demonstration of how to navigate in the `Business Center`, see this YouTube video: [watch?v=2qi_g2DParI](https://www.youtube.com/watch?v=2qi_g2DParI "") Managing Report Subscriptions : For an overview of how to manage report subscriptions in the Downloadable Reports section in the `Business Center`, see this YouTube video: [watch?v=tFlmkXtvxWE](https://www.youtube.com/watch?v=tFlmkXtvxWE "") Downloading Reports : For an overview of how to download available reports in the Reports section of the `Business Center`, see this YouTube video: [watch?v=E0slUYjJvmw](https://www.youtube.com/watch?v=E0slUYjJvmw "") Configure Alternative Payments Methods in the `Business Center` {#manage-self-enable-altpay} ============================================================================================ Follow these steps to configure alternative payment methods in the `Business Center`: 1. In the left navigation panel, click the **Available Products** icon. The Available Products page appears.{#manage-self-enable-altpay_step-1} {#manage-self-enable-altpay_step-1} 2. In the Alternative Payment Methods section, click **Enable**.{#manage-self-enable-altpay_step-2} {#manage-self-enable-altpay_step-2} 3. Check the box next to each alternative payment method you want to enable and configure. You can choose alternative payment methods from these categories: * Bank Transfer * Buy Now Pay Later (BNPL) * Card Payment * Direct Debit * eWallet * Gift Card * Local Card * Post Pay Reference * QR 4. Click Continue. The Product Configuration page appears. 5. Enter the required details for each alternative payment method you want to configure. Click Copy to other sections to populate the information to any other alternative payment methods that you selected. > IMPORTANT > You must select I have read and agree to the Terms and Conditions for each alternative payment method you want to enable. 6. Click **Continue** to return to the Available Products page.{#manage-self-enable-altpay_step-6} {#manage-self-enable-altpay_step-6} Configure the Transacting Organization and Products {#boarding-merchants-v2-add-trans-org-prod} =============================================================================================== Follow these steps to modify the transacting organization details, or to enable and configure products for the transacting organization: 1. Click **Start** in the Transacting Organization and Products section. The Transacting Organization and Products page is displayed. 2. Optional: modify the name and ID of the organization by using the text fields in the Transacting Organization Details section. By default, the name is the merchant name with 001 added to the end of the name. If you accept this default, additional transacting organizations will have default names that iterate the numbers at the end of their names, beginning with 002. 3. Optional: to edit the organization information, Click **Edit** in the Transacting Organization Information section. After editing, click **Apply**. 4. To enable a product in the Product Enablement section, click the Enablement drop-down menu and select **Enabled**. 5. To modify the configuration, click the **Edit** or **configure** button (depending on the product). Some products are not configurable. 6. To confirm the configuration, click **Apply**. 7. To save all product configurations, click **Save**. You are returned to the Add Merchant page. 8. To continue working with this organization, click **Continue working with this merchant** . To finish and return to Merchant Management, click **Return to merchant management**. Add Merchant Account Information {#boarding-merchants-v2-add-merch-acct-info} ============================================================================= Follow these steps to add merchant account information: 1. In Basic Information, enter the merchant account name and the organization ID in the provided text fields. #### ADDITIONAL INFORMATION * The merchant account name is the name of the business. * The organization ID is the name or identifier of the account that you are creating. It must be unique, not just in the portfolio or account, but in the system. 2. Enter the merchant information in the provided text fields. Required fields are noted with an asterisk (\*). 3. Click **Save** . You are returned to the Add Merchant page. You can skip the optional hierarchy step by clicking **Skip**. Set Up the Transacting Organization and Products {#boarding-merchants-v2-add-merch-trans-org-prod} ================================================================================================== The transacting organization is the entity that processes transactions. Follow these steps to create a transacting organization and configure products for it: 1. Click **Start** in the Transacting Organization and Products section. The Transacting Organization and Products page is displayed. 2. Optional: modify the name and ID of the organization by using the text fields in the Transacting Organization Details section. The ID must be unique, not just in the portfolio or account, but across the system. By default, the name is the merchant name with 001 added to the end of the name. If you accept this default, additional transacting organizations will have default names that iterate the numbers at the end of their names, beginning with 002. 3. Optional: By default, the organization information is inherited from the parent organization. To edit the organization information, click **Edit** in the Transacting Organization Information section. After editing, click **Apply**. 4. To enable a product in the Product Enablement section, click the Enablement drop-down menu and select **Enabled**. 5. To modify the configuration, click the **Edit** or **Configure** button (depending on the product). Some products are not configurable. 6. To confirm the configuration, click **Apply**. 7. To save all product configurations, click **Save**. You are returned to the Add Merchant page. 8. To continue working with this organization, click **Continue working with this merchant** . To finish and return to Merchant Management or to add another merchant, click **Return to merchant management**. #### ADDITIONAL INFORMATION The image below shows the Transacting Organization and Products page. #### Figure: {#boarding-merchants-v2-add-merch-trans-org-prod_transacting} Transacting Organization and Products ![](/content/dam/new-documentation/documentation/en-us/topics/platform/bam/boarding-user/images/transacting_org.PNG/jcr:content/renditions/original)