GoCardlessDeveloper Docs
Create a sandbox account

Send your first API request#

View as Markdown

Create your first test payment authorisation in 5 minutes#

We'll walk you through making your first API requests by creating and completing a Billing Request, which allows customers to securely authorise payments.

Creating a billing request#

A Billing Request enables you to collect all types of GoCardless payments. For now, we'll handle a recurring, direct debit (mandate) request.

01. Create your first billing request#

Copy your access token from the Developers page in the GoCardless dashboard.

ACCESS_TOKEN="your_access_token_here"

Create your first billing request by sending the request below.

POST https://api.gocardless.com/billing_requests HTTP/1.1
Content-Type: application/json
{
"billing_requests": {
  "mandate_request": {
    "scheme": "bacs"
  }
}
}

HTTP/1.1 201 Created
Location: /billing_requests/BRQ123
Content-Type: application/json
{
"billing_requests": {
"id": "BRQ123",
"created_at": "2023-03-22T15:20:08.397Z",
"status": "pending",
"mandate_request": {
"currency": "GBP",
"scheme": "bacs",
"links": {}
},
...
}
curl --silent \
-H "Content-Type: application/json" \
-H "Gocardless-Version: 2015-07-06" \
-H "Authorization: Bearer ${API_ACCESS_TOKEN}" \
"https://api.gocardless.com/billing_requests" \
-d @- << EOF
{
"billing_requests": {
"mandate_request": {
"scheme": "bacs"
}
}
}
EOF
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);

$client->billingRequests()->create([
"params" => [
"mandate_request" => [
"scheme" => "bacs"
]
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.billing_requests.create(params={
"mandate_request": {
"scheme": "bacs"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)

billing_request = @client.billing_requests.create(
params: {
mandate_request: {
scheme: "bacs"
}
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();

BillingRequest billingRequest = client.billingRequests().create()
.withMandateRequestScheme("bacs")
.execute();
import { GoCardlessClient } from "gocardless-nodejs/client";
import constants from "gocardless-nodejs/constants";

export const client = new GoCardlessClient(
process.env.GOCARDLESS_ACCESS_TOKEN,
constants.Environments.Sandbox,
);

const billingRequest = await client.billingRequests.create({
mandate_request: {
scheme: "bacs",
},
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var mandateRequest = new GoCardless.Services.BillingRequestCreateRequest.BillingRequestMandateRequest
{
Scheme = "bacs",
};

var resp = await gocardless.BillingRequests.CreateAsync(
new GoCardless.Services.BillingRequestCreateRequest()
{
MandateRequest = mandateRequest,
}
);

GoCardless.Resources.BillingRequest billingRequest = resp.BillingRequest;
package main

import (
gocardless "github.com/gocardless/gocardless-pro-go/v6"
)

accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}

billingRequestCreateParams := gocardless.BillingRequestCreateParams{
MandateRequest: &gocardless.BillingRequestCreateParamsMandateRequest{
Scheme: "bacs",
},
}

billingRequest, err := client.BillingRequests.Create(context, billingRequestCreateParams)
import GoCardlessSDK

let billingRequest = BillingRequest(
mandateRequest: MandateRequest(scheme: "bacs")
)

GoCardlessSDK.shared.billingRequestService.createBillingRequest(billingRequest: billingRequest)
.receive(on: DispatchQueue.main)
.sink(receiveCompletion: { completion in
if case let .failure(error) = completion {
print("Failed to create billing request: \(error)")
}
}) { createdBillingRequest in
let billingRequestId = createdBillingRequest.id
print("Successfully created billing request with ID: \(billingRequestId)")
}
.store(in: &subscriptions)
import com.gocardless.gocardlesssdk.GoCardlessSDK
import com.gocardless.gocardlesssdk.model.BillingRequest
import com.gocardless.gocardlesssdk.model.MandateRequest
import com.gocardless.gocardlesssdk.network.ApiError
import com.gocardless.gocardlesssdk.network.ApiSuccess
import com.gocardless.gocardlesssdk.network.Environment
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

GoCardlessSDK.initSDK(
"YOUR_ACCESS_TOKEN",
Environment.Sandbox
)

val billingRequest = BillingRequest(
mandateRequest = MandateRequest(scheme = "bacs")
)

runBlocking { // In a real app, use a scope like viewModelScope
launch {
val result = GoCardlessSDK.billingRequestService.createBillingRequest(billingRequest)

      when (result) {
          is ApiSuccess -> {
              val createdBillingRequest = result.value
              val billingRequestId = createdBillingRequest.id
              println("Successfully created billing request with ID: $billingRequestId")
          }
          is ApiError -> {
              println("Failed to create billing request: ${result.error.message}")
          }
      }
  }

}

02. Create your payment link#

Creating a Billing Request Flow, powered by GoCardless hosted payment pages, generates an authorisation link for collecting payments.

POST https://api.gocardless.com/billing_request_flows HTTP/1.1
Content-Type: application/json
{
"billing_request_flows": {
  "links": {
    "billing_request": "your_billing_request_id"
  }
}
}

HTTP/1.1 201 Created
Location: /billing_request_flows/BRF123456
Content-Type: application/json
{
"billing_request_flows": {
"id": "BRF123456",
"authorisation_url": "https://pay.gocardless.com/billing/static/flow?id=BRF123456",
"links": {
"billing_request": "BRQ123"
},
...
}
}
BRQ_ID="your_billing_request_id"

curl --silent \
-H "Content-Type: application/json" \
-H "Gocardless-Version: 2015-07-06" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://api.gocardless.com/billing_request_flows" \
-d @- << EOF
{
"billing_request_flows": {
"links": {
"billing_request": "$BRQ_ID"
}
}
}
EOF
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);

$client->billingRequestFlows()->create([
"params" => [
"links" => [
"billing_request" => "your_billing_request_id"
]
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.billing_request_flows.create(params={
"links": {
"billing_request": "your_billing_request_id"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)

@client.billing_request_flows.create(
params: {
links: {
billing_request: "your_billing_request_id",
}
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();

BillingRequestFlow billingRequestFlow = client.billingRequestFlows().create()
.withLinksBillingRequest("your_billing_request_id")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);

const billingRequestFlow = await client.billingRequestFlows.create({
links: {
billing_request: "your_billing_request_id",
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.BillingRequestFlows.CreateAsync(
new GoCardless.Services.BillingRequestFlowCreateRequest()
{
Links = new gocardless.BillingRequestFlowCreateRequest.BillingRequestFlowLinks
{
BillingRequest = "your_billing_request_id",
},
}
);

GoCardless.Resources.BillingRequestFlow billingRequestFlow = resp.BillingRequestFlow;
package main

import (
gocardless "github.com/gocardless/gocardless-pro-go/v6"
)

func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}

billingRequestFlowCreateParams := gocardless.BillingRequestFlowCreateParams{
Links: gocardless.BillingRequestFlowCreateParamsLinks{
BillingRequest: "your_billing_request_id",
},
}

billingRequestFlow, err := client.BillingRequestFlows.Create(context, billingRequestFlowCreateParams)

}
import GoCardlessSDK

GoCardlessSDK.initSDK(accessToken: "YOUR_ACCESS_TOKEN", environment: .sandbox) {
print("GoCardless SDK is initialised")
}

let billingRequestFlow = BillingRequestFlow(
links: Links(billingRequest: "your_billing_request_id")
)

GoCardlessSDK.shared.billingRequestFlowService.createBillingRequestFlow(billingRequestFlow: billingRequestFlow)
.receive(on: DispatchQueue.main)
.sink(receiveCompletion: { completion in
switch completion {
case let .failure(error):
print("API error: \(error)")
self.state = .error
case .finished:
break
}
}) { createdFlow in
self.state = .success(flow: createdFlow)
}
.store(in: &subscriptions)
import com.gocardless.gocardlesssdk.GoCardlessSDK
import com.gocardless.gocardlesssdk.model.BillingRequestFlow
import com.gocardless.gocardlesssdk.model.Links
import com.gocardless.gocardlesssdk.network.ApiError
import com.gocardless.gocardlesssdk.network.ApiSuccess
import com.gocardless.gocardlesssdk.network.Environment
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

GoCardlessSDK.initSDK(
accessToken = "YOUR_ACCESS_TOKEN",
environment = Environment.SANDBOX
)

val billingRequestFlow = BillingRequestFlow(
links = Links(billingRequest = "YOUR_BILLING_REQUEST_ID")
)

runBlocking { // In a real app, use a scope like viewModelScope
launch {
val result = GoCardlessSDK.billingRequestFlowService.createBillingRequestFlow(billingRequestFlow)

      when (result) {
          is ApiSuccess -> {
              val createdFlow = result.value
              println("Successfully created flow: ${createdFlow.id}")
          }
          is ApiError -> {
              val error = result.error
              println("API error: ${error.message}")
          }
      }
  }

}

Copy the authorisation_url from the response — you can share this with customers to complete the billing request via a button on your website, SMS, email, or any other channel.

03. Customer completes billing request#

You can now act as your customer would. Go to the authorisation link and enter the details.

For testing purposes, use sort code 200000 and account number 55779911 to complete the billing request.

Customer completing the billing request flow

04. View your first customer#

You should now be able to see your newly created customer on the customers page in the dashboard.

Your first customer on the GoCardless dashboard

Next steps#

Create a payment

Create your first test payment using the mandate you just set up.

Learn more
Partner integrations

Accept bank payments directly within your software. Connect to your users' GoCardless accounts with OAuth 2.0.

Learn more
SupportDashboard