Skip to main content
The Payments API allows you to create and manage payment transactions. Use this API to charge cards, record external payments, and handle payment lifecycle operations.

​
Client Methods

​
List Payments

Retrieves a list of payments taken by the account making the request. 
client.Payments.List(ctx context.Context, request *square.ListPaymentsRequest) (*square.ListPaymentsResponse, error)
​
request
*square.ListPaymentsRequest
Request parameters for listing payments
​
response
*square.ListPaymentsResponse
The list of payments
request := &square.ListPaymentsRequest{
    BeginTime: square.String("2024-01-01T00:00:00Z"),
    EndTime: square.String("2024-12-31T23:59:59Z"),
    SortOrder: square.String("DESC"),
    LocationID: square.String("L88917AVBK2S5"),
    Limit: square.Int(10),
    SortField: square.ListPaymentsRequestSortFieldCreatedAt.Ptr(),
}

response, err := client.Payments.List(context.TODO(), request)
if err != nil {
    log.Fatal(err)
}

​
Create Payment

Creates a payment using the provided source. You can use this endpoint to charge a card or record a payment that the seller received outside of Square. 
client.Payments.Create(ctx context.Context, request *square.CreatePaymentRequest) (*square.CreatePaymentResponse, error)
​
request
*square.CreatePaymentRequest
required
Request parameters for creating a payment
​
response
*square.CreatePaymentResponse
The created payment details
request := &square.CreatePaymentRequest{
    SourceID: "ccof:GaJGNaZa8x4OgDJn4GB",
    IdempotencyKey: "7b0f3ec5-086a-4871-8f13-3c81b3875218",
    AmountMoney: &square.Money{
        Amount: square.Int64(int64(1000)),
        Currency: square.CurrencyUsd.Ptr(),
    },
    Autocomplete: square.Bool(true),
    CustomerID: square.String("W92WH6P11H4Z77CTET0RNTGFW8"),
    LocationID: square.String("L88917AVBK2S5"),
    ReferenceID: square.String("123456"),
    Note: square.String("Brief description"),
}

response, err := client.Payments.Create(context.TODO(), request)
if err != nil {
    log.Fatal(err)
}

​
Get Payment

Retrieves details for a specific payment. 
client.Payments.Get(ctx context.Context, request *square.GetPaymentsRequest) (*square.GetPaymentResponse, error)
​
PaymentID
string
required
A unique ID for the desired payment.
request := &square.GetPaymentsRequest{
    PaymentID: "payment_id",
}

response, err := client.Payments.Get(context.TODO(), request)
if err != nil {
    log.Fatal(err)
}

​
Update Payment

Updates a payment with the APPROVED status. You can update the amount_money and tip_money using this endpoint. 
client.Payments.Update(ctx context.Context, request *square.UpdatePaymentRequest) (*square.UpdatePaymentResponse, error)
​
request
*square.UpdatePaymentRequest
required
request := &square.UpdatePaymentRequest{
    PaymentID: "payment_id",
    Payment: &square.Payment{
        AmountMoney: &square.Money{
            Amount: square.Int64(int64(1000)),
            Currency: square.CurrencyUsd.Ptr(),
        },
        TipMoney: &square.Money{
            Amount: square.Int64(int64(100)),
            Currency: square.CurrencyUsd.Ptr(),
        },
        VersionToken: square.String("ODhwVQ35xwlzRuoZEwKXucfu7583sPTzK48c5zoGd0g6o"),
    },
    IdempotencyKey: "956f8b13-e4ec-45d6-85e8-d1d95ef0c5de",
}

response, err := client.Payments.Update(context.TODO(), request)
if err != nil {
    log.Fatal(err)
}

​
Cancel Payment

Cancels (voids) a payment. You can use this endpoint to cancel a payment with the APPROVED status. 
client.Payments.Cancel(ctx context.Context, request *square.CancelPaymentsRequest) (*square.CancelPaymentResponse, error)
​
PaymentID
string
required
The ID of the payment to cancel.
request := &square.CancelPaymentsRequest{
    PaymentID: "payment_id",
}

response, err := client.Payments.Cancel(context.TODO(), request)
if err != nil {
    log.Fatal(err)
}

​
Complete Payment

Completes (captures) a payment. By default, payments are set to complete immediately after they are created. You can use this endpoint to complete a payment with the APPROVED status. 
client.Payments.Complete(ctx context.Context, request *square.CompletePaymentRequest) (*square.CompletePaymentResponse, error)
​
request
*square.CompletePaymentRequest
required
request := &square.CompletePaymentRequest{
    PaymentID: "payment_id",
}

response, err := client.Payments.Complete(context.TODO(), request)
if err != nil {
    log.Fatal(err)
}

​
Cancel Payment By Idempotency Key

Cancels (voids) a payment identified by the idempotency key that is specified in the request. Use this method when the status of a CreatePayment request is unknown. 
client.Payments.CancelByIdempotencyKey(ctx context.Context, request *square.CancelPaymentByIdempotencyKeyRequest) (*square.CancelPaymentByIdempotencyKeyResponse, error)
​
IdempotencyKey
string
required
The idempotency_key identifying the payment to be canceled.
request := &square.CancelPaymentByIdempotencyKeyRequest{
    IdempotencyKey: "a7e36d40-d24b-11e8-b568-0800200c9a66",
}

response, err := client.Payments.CancelByIdempotencyKey(context.TODO(), request)
if err != nil {
    log.Fatal(err)
}

​
Learn More

Build docs developers (and LLMs) love

Get started for freeTalk to us