Overview

This guide shows you how to integrate with our API to accept crypto payments. The process is simple: you create a payment intent, the customer scans the QR code with their Bitso app, and you get real-time status updates via webhooks.

Step-by-Step

The payment process is a structured sequence of actions between your system, Bitso, and the customer.

1. Create Payment Intent

Your system sends a POST request to the /payments/v1alpha/payment_intents endpoint following the API Rerefence.

Bitso action:

• Bitso immediately sends a webhook with a CREATED status, confirming the payment intent was successfully created.

2. Display QR Code

Use the universal link from the response to generate and display a QR code for the customer.

3. Customer Scans the QR Code

The customer opens the Bitso app and scans the QR code. The app automatically opens to the payment confirmation screen.

Bitso action:

• Bitso sends a PENDING status webhook as soon as the customer accesses the payment link.

4. Track the Payment

While the customer confirms the transaction in the Bitso app, you receive updates via webhook.

• PROCESSING: The transaction has begun processing.
• COMPLETED: The payment was successfully finalized.
• FAILED: The payment could not be completed.

Payment Flow Diagram

Below, a sequence diagram details the complete payment flow, from intent creation to the final transaction status.

sequenceDiagram
    participant M as Merchant
    participant B as Bitso
    participant U as User

    M->>B: POST /payments/v1alpha/payment_intents
    B-->>M: Universal Link + Intent ID
    B-->>M: Webhook (CREATED)

    M->>U: Display QR Code

    U->>B: Scan QR Code
    B-->>M: Webhook (PENDING)

    U->>U: Select Asset in App

    B-->>M: Webhook (PROCESSING)

    U->>U: Confirm Payment

    B-->>M: Webhook (COMPLETED/FAILED)

Status Lifecycle

Your payment intent can transition through various statuses. It's crucial that your integration handles all of them.

• CREATED: Payment intent created.
• PENDING: Customer has accessed the payment link.
• PROCESSING: Payment is being processed.
• COMPLETED: Payment is complete.
• FAILED: Payment could not be completed.
• EXPIRED: The time limit for payment has expired.

Possible Transitions

The following image illustrates how statuses can change:

Webhook Structure

Each webhook sent by Bitso will follow this structure:

{
  "id": "payment_intent_id",
  "status": "CREATED|PENDING|PROCESSING|COMPLETED|FAILED|EXPIRED",
  "timestamp": "2024-01-01T12:00:00Z",
  "amount": "100.00",
  "asset": "BTC",
  "merchant_id": "merchant_id"
}

Best Practices

• Validation: Always validate the webhook signature to ensure the request is from Bitso. See Webhook Signatures.
• Retries: Implement a retry logic to process webhooks in case your system fails to receive them.
• Testing: Use lower environments to test all status transitions before going live.
• Error Handling: Build a robust system to handle failed or expired payments, ensuring a good experience for the customer.