4 Payment Flow

This guide provides a comprehensive walkthrough for developers on how to integrate the Bubl payment system into a service.

The payment process is designed as a three-step workflow involving your service’s frontend (UI), your service’s backend, and the central Bubl Controller for payment processing.

1. Initiate Payment: Your backend communicates with the Bubl Controller to create a new payment transaction.
2. Make Payment: Your frontend receives a payment ID and directly calls the Bubl Controller to get a checkout URL, to which the user is redirected.
3. Check Payment Status: After payment, the user is redirected back to your application. Your backend then verifies the payment status with the Bubl Controller.

When a frontend makes a call to your backend API, the Bubl platform invokes your backend service with the following flags, providing the necessary context from the original HTTP request:

The first step is to create a payment transaction.

Flow: UI -> Your Backend -> Bubl Controller

1. UI to Backend Request: The UI calls an endpoint on your backend to start the payment process.

   • Endpoint: https://<bubl_domain>/service/v1/<app_id>/api/v1/initiatepayment
   • Method: POST
   • Example Request Body:

     {
         "paymentOption": 1,
         "language": "en_US",
         "consultuuid": "<consultuuid>"
     }
     

     This request body is specific to your service. Your backend will use this information to determine payment details like amount and currency.

2. Backend to Bubl Controller Request: Your backend receives the request and is invoked with the following flags:

   • -p: /v1/initiatepayment
   • -m: POST

   It then uses the provided flags to call the Bubl Controller’s initpayment endpoint.

   • Endpoint: <local-server>/payments/initpayment (from the -d flag)
   • Method: POST
   • Headers: Use the token from the -t flag for authorization.
   • Request Body:

     {
         "amount": 30.00,
         "currency": "EUR",
         "description": "Description for the payment",
         "forward": "/#/newconsult/paymentconfirm",
         "language": "en_US"
     }
     

     • forward: This is a relative URL path on your frontend where the user will be redirected after completing the payment. The Bubl Controller will append the paymentid as a query parameter.

3. Bubl Controller Response: The controller returns a response containing the unique payment ID.

   • Example Response Body:

     {
         "bublPaymentUuid": "<payment_id>",
         "amount": 30,
         "currency": "EUR",
         "language": "en_US"
     }
     

4. Backend to UI Response: Your backend should forward this response to the UI. It’s recommended to store the bublPaymentUuid in your database, associating it with the relevant context (e.g., consultuuid).

With the bublPaymentUuid, the UI can now request the checkout URL.

Flow: UI -> Bubl Controller

1. UI to Bubl Controller Request: The UI calls the makepayment endpoint on the Bubl Controller directly.

   • Endpoint: https://<bubl_domain>/co-nect/v1/payments/makepayment
   • Method: POST
   • Example Request Body:

     {
         "bublPaymentUuid": "<bublPaymentUUID>",
         "paymentInfo": {
             "Method": "ideal",
             "Issuer": "ideal_ABNANL2A"
         },
         "serviceId": "<your_app_id>",
         "billingAddress": {
             "name": { "firstName": "John", "lastName": "Doe" },
             "Address": {
                 "houseNumber": "123",
                 "street": "Main St",
                 "city": "Springfield",
                 "zipcode": "62704",
                 "Country": "US"
             }
         }
     }
     

2. Bubl Controller Response: The controller responds with the URL for the payment checkout page.

   • Example Response Body:

     {
         "checkout": "<checkout_url>"
     }
     

3. Redirection: The UI must redirect the user to the received checkout URL to complete the payment.

After the user completes the payment, they are redirected back to the forward URL specified in Step 1. The UI must then verify the payment’s final status.

Flow: UI -> Your Backend -> Bubl Controller

1. Callback and Status Check Trigger: The user lands on your forward URL, which will include the paymentid as a query parameter (e.g., /#/newconsult/paymentconfirm?paymentid=<payment_id>). The UI should extract the paymentid and call your backend to get the payment status.

   • Endpoint: https://<bubldomain>/service/v1/<appid>/api/v1/paymentstatus/<paymentid_from_query>
   • Method: GET

2. Backend to Bubl Controller Request: Your backend is invoked with the following flags:

   • -p: /v1/paymentstatus/<paymentid_from_query>
   • -m: GET

   It then calls the Bubl Controller’s status endpoint.

   • Endpoint: <local-server>/payments/status?bublPaymentUuid=<paymentid_from_query>
   • Method: GET
   • Headers: Use the token from the -t flag for authorization.

3. Bubl Controller Response: The controller returns the payment status.

   • Example Response Body:

     {
         "bublPaymentUuid": "<paymentid_from_query>",
         "status": 300,
         "statusInfo": "paid"
     }
     

   • Status Codes:
     • 300 (paid): Payment successful.
     • 200 (open, pending): Payment is still in progress.
     • 400 (cancelled, expired, failed): Payment was not successful.

4. Backend to UI Response: Your backend forwards this status to the UI. Your backend can also trigger other processes, such as sending a confirmation email. The UI can then display the appropriate success or error message to the user.