This guide explains using the billing profile reference and the ID with the Drop-In API.

The billing profile reference

A billing profile reference (BillingProfileReference) is a unique identifier that the Drop-In API uses to manage and access customer billing profiles. It can include payment methods, billing addresses, and settings related to the customer's billing preferences. You can use the BillingProfileReference to link a specific billing profile to customer transactions, handle recurring payments, manage subscriptions, and determine customer billing preferences.

This request assumes you created a previous session with the BillingProfileReference supplied as MerchantSupplied-reference (see the request and response examples below). You can verify that the billing profile in the response matches a previously provided billing profile.

ℹ️
Note
The billing profile reference is similar to the example using the billing profile ID. However, the critical distinction is that in you supplied the BillingProfileReference a previous request, whereas the BillingProfileId is a value Reach generated and provided in a response.

    # Location
    POST https://api.withreach.com/v1/session

    #Headers
    Authorization: Basic YWNjb3VudDpzZWNyZXQ=
    Content-Type: application/json
    
    #Body
    {
        "MerchantReference": "unique_reference_provided_by_merchant",
        "Currency": "USD",
        "Items": [
            {
                "Name": "Item 1",
                "Amount": 10.00,
                "Quantity": 1
            }
        ],
        "BillingProfileReference": "MerchantSupplied-reference",
        "AutoCapture": true,
        "CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
        "CancelUrl": "https://www.send-user-here-after-failed-redirect.com"
    }

    #Headers
    Content-Type: application/json
    
    #Body
    {
        "SessionId": "88907fca-ffbd-49e6-9f15-df0ed0d2b51a",
        "State": "CREATED",
        "MerchantReference": "verify_docs_3",
        "Items": [
            {
                "Name": "Item 1",
                "Amount": 10.0,
                "Quantity": 1
            }
        ],
        "Currency": "USD",
        "TotalAmount": 10.0,
        "BillingProfile": {
            "BillingProfileId": "da7e625b-1d6d-4693-9708-e7bdbcb35df3",
            "BillingProfileReference": "MerchantSupplied-reference",
            "Name": "First Last",
            "Email": "[email protected]",
            "NationalIdentifier": "43.236.560/0001-52",
            "Birthdate": "1980-01-02",
            "Company": "Umbrella corp",
            "Address": {
                "Street": "123 Sreet",
                "City": "City",
                "Region": "SC",
                "Country": "BR",
                "Postcode": "12345678"
            }
        },
        "AutoCapture": true,
        "CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
        "CancelUrl": "https://www.send-user-here-after-failed-redirect.com",
        "ViaAgent": false

The billing profile ID

To use a billing profile ID in your request, you must have created it before interacting with the API. In other words, you must have a session in which the billing profile was successfully set up and returned by the Drop-In API before you can reference that billing profile ID.

The billing profile ID is a value that the system generates. Unlike the billing profile reference, an identifier you provide, the Drop-In API generates the billing profile ID as part of its internal management of billing profiles.

Including the billing profile ID in a request (see the example below) helps the Drop-In API understand which billing profile to use for processing the payment.

    # Location
    POST https://api.withreach.com/v1/session

    #Headers
    Authorization: Basic YWNjb3VudDpzZWNyZXQ=
    Content-Type: application/json
    
    #Body
    {
        "MerchantReference": "unique_reference_provided_by_merchant",
        "Currency": "USD",
        "Items": [
            {
                "Name": "Item 1",
                "Amount": 10.00,
                "Quantity": 1
            }
        ],
        "BillingProfileId": "da7e625b-1d6d-4693-9708-e7bdbcb35df3",
        "AutoCapture": true,
        "CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
        "CancelUrl": "https://www.send-user-here-after-failed-redirect.com"
    }

    #Headers
    Content-Type: application/json
    
    #Body
    {
        "SessionId": "88907fca-ffbd-49e6-9f15-df0ed0d2b51a",
        "State": "CREATED",
        "MerchantReference": "verify_docs_3",
        "Items": [
            {
                "Name": "Item 1",
                "Amount": 10.0,
                "Quantity": 1
            }
        ],
        "Currency": "USD",
        "TotalAmount": 10.0,
        "BillingProfile": {
            "BillingProfileId": "da7e625b-1d6d-4693-9708-e7bdbcb35df3",
            "BillingProfileReference": "MerchantSupplied-reference",
            "Name": "First Last",
            "Email": "[email protected]",
            "NationalIdentifier": "43.236.560/0001-52",
            "Birthdate": "1980-01-02",
            "Company": "Umbrella corp",
            "Address": {
                "Street": "123 Sreet",
                "City": "City",
                "Region": "SC",
                "Country": "BR",
                "Postcode": "12345678"
            }
        },
        "AutoCapture": true,
        "CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
        "CancelUrl": "https://www.send-user-here-after-failed-redirect.com",
        "ViaAgent": false