Using Payment Links

Payment links facilitate billing users for Gigs subscriptions through a checkout page. This simplifies the payment process and automates subscription activation. This guide will walk you through how payment links work and how to integrate them into your application.

To use payment links, you must enable billing users.

Overview

When a subscription requires payment to activate, payment links provide a solution. By creating a Payment Link via the Gigs API, you get a URL that directs users to a checkout flow powered by the payment provider. Once the payment is completed, the associated subscription is activated automatically.

How Payment Links Work

1. Payment Link Generation: Use the Gigs API to create a payment link linked to an invoice. This link contains a payment URL that renders an payment page hosted by the provider.
2. User Payment: The user completes the payment on the checkout page. The applicable taxes are automatically calculated on the invoice and displayed at checkout.
3. Subscription Activation: Once the payment is successful, the subscription tied to the invoice is activated automatically, streamlining the transition from payment to service access.

Steps to Use Payment Links

1. Create a Subscription and Retrieve the Invoice

Start by creating a subscription with billed activation for the user. See creating billed subscriptions for more details.

Once the subscription is created, get its invoice. The invoice ID is used to generate the payment link.

2. Create the Payment Link

To create a payment link, you need to provide the invoice and other details, such as the user's full name, email, and tax number (currently only Brazilian CPF). The user information is passed directly to the provider and is not stored by Gigs.

To control the user redirection after payment, specify a redirectUrl when creating the payment link. After the payment, the user is redirected to this URL, regardless of the payment status (success or failure).

This request generates a payment link associated with the specified invoice.

curl --request "POST" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/paymentLinks" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
    "type": "ebanx",
    "ebanx": {
      "user": {
        "fullName": "Elaine Benes",
        "email": "elaine@example.com",
        "taxNumber": "290.063.072-03"
      },
      "redirectUrl": "https://example.com"
    }
  }'

3. Render the Payment Flow

Use the payment URL provided in the payment link response to direct your end users to the checkout page. This URL renders the provider payment flow, where users complete their payment.

{
  "object": "paymentLink",
  "id": "pml_0SNlurA049MEWV1x2CfC8u8im5xU",
  "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "paymentUrl": "https://api.ebanx.com/ws/redirect/execute?hash=64f2...",
  (...)
}

4. Handle Payment Completion

• Success: When the payment is successful, the event paymentLink.completed is sent, confirming the payment. The successful payment marks the invoice as paid and activates the subscription, triggering the subscription.activated event .
• Failure: If the payment fails, the event paymentLink.canceled is sent, indicating that the payment link is canceled and that a new payment link needs to be created for a new payment attempt. A canceled payment link cannot be used again.

By following these steps, you can integrate payment links into your application to efficiently manage subscription payments.

Do you have questions or feedback to provide? We'd love to hear from you at support@gigs.com.