Create payment link

POST/payment-links

Route to create payment link.

Send the business identifier in the business-id header, the recommended one, or in the x-business-id header. The user of the API key must be a collaborator of that business, a seller of an active sales team of that business, or an Easyflow platform administrator. A request without the business identifier returns 401 with BusinessId is required, a request that sends business-id and x-business-id with different values returns 401, a value that is not a business identifier returns 400 with Invalid param: [businessId], and a user that is not linked to the business gets 403.

The payment link is created with the draft status. When paymentConfiguration.billet.dueDateDelay is sent, preference.requestAddress is set to true.

valueInCents must be greater than zero. A value equal to or lower than zero returns 400 with Error: The field valueInCents must be bigger than zero, without errorCode, before the recurrence rules below are checked.

Recurring payment link:

  • Send subscription to make the payment link recurring. Each buyer who subscribes through it with a credit card starts a subscription with these terms. The subscription is created as soon as the first order is charged, whatever the result of the card: Easyflow sends subscription.created, and, if the first order is refused, the subscription is canceled and Easyflow sends subscription.canceled. The payment link is saved with supportedPaymentMethods equal to ["credit-card"].
  • With subscription, valueInCents must be an integer equal to or greater than the minimum charge value of the platform (by default, 1000). Otherwise the API returns 400 with Invalid param: [valueInCents] and errorCode PAYMENT_LINK_SUBSCRIPTION_BELOW_MINIMUM_VALUE.
  • With subscription, supportedPaymentMethods must be omitted or contain only credit-card. A list with another method, null or an empty list returns 400 with Invalid param: [supportedPaymentMethods] and errorCode PAYMENT_LINK_SUBSCRIPTION_CREDIT_CARD_ONLY.
  • An invalid field of subscription returns 400 with the field name prefixed by subscription., such as Missing param: [subscription.periodicity], Invalid param: [subscription.numberRecurrences] or Invalid param: [subscription.retry.intervalInDays].
  • A recurring payment link cannot be paid with Create charge. The buyer subscribes through the Easyflow checkout of the payment link.

Headers

  • x-api-keystringrequired

    Api key provided on integrations tab in Easyflow platform.

  • x-api-secretstringrequired

    Api Secret provided on integrations tab in Easyflow platform.

  • business-idstringrequired

    Identifier of the business the request refers to. The user of your API key must be linked to this business, as explained in The business identifier. A value that is not a business identifier returns 400 with Invalid param: [businessId], a business that the user is not linked to returns 403, and a request that also sends x-business-id with a different value returns 401.

Request body

Content typeapplication/jsonobject

  • namestringrequired
  • descriptionstringrequired
  • valueInCentsintegerrequired

    Value of the payment link in cents. Must be greater than zero.

  • checkoutTemplateIdstring · uuid

    ID of the checkout template. When omitted, the default checkout template of the business is used.

  • preferenceobject

    Data that the checkout of the payment link asks from the buyer.

    Show child attributesHide child attributes
    • acceptNaturalPersonBuyerboolean
    • acceptCorporationBuyerboolean
    • requestAddressboolean
    • requestDeliveryAddressboolean
    • requireEmailReentryboolean
    • disableCouponFormboolean

      Default:false

  • paymentConfigurationobject
    Show child attributesHide child attributes
    • billetobject
      Show child attributesHide child attributes
      • dueDateDelayinteger
    • pixobject
      Show child attributesHide child attributes
      • expirationInMinutesinteger
    • creditCardobject
      Show child attributesHide child attributes
      • defaultInstallmentsinteger
      • maxInstallmentsinteger
      • invoiceDescriptionstring
      • installmentOptionsarray of objects
        Show child attributesHide child attributes
        • installmentsinteger
        • installmentValueInCentsintegernullable
        • interestRateintegernullable
  • supportContactobject

    Support contact shown to the buyer. When omitted, the default contact email of the business is used.

    Show child attributesHide child attributes
    • contactEmailIdstring · uuidrequired

      ID of a validated contact email of the business.

  • advancedobject
    Show child attributesHide child attributes
    • redirectobject

      Redirect shown to the buyer after the payment.

      Show child attributesHide child attributes
      • urlstring
      • buttonNamestring
      • delayInSecondsintegernullable
    • buyerWhitelistobject
      Show child attributesHide child attributes
      • emailDomainsarray of strings

        Email domains allowed to buy with the payment link, such as example.com. Empty or omitted means that any email can buy.

  • interestSettingsobject
    Show child attributesHide child attributes
    • sellerAbsorbsInterestbooleanrequired

      When true, the seller absorbs the installment interest and every installment option has an interest rate of 0.

  • payerobject

    Data of the payer of the payment link.

    Show child attributesHide child attributes
    • namestringrequired
    • emailstringrequired
    • documentobjectrequired
      Show child attributesHide child attributes
      • typestringrequired

        Possible values:CPFCNPJ

      • numberstringrequired

        Document number with digits only.

    • phoneobject
      Show child attributesHide child attributes
      • areaCodestring

        Example:+55

      • dddstring

        Example:11

      • numberstring

        Example:912345678

      • isMobileboolean
    • addressobject
      Show child attributesHide child attributes
      • zipCodestring

        Zip code with digits only, such as 01310100.

      • streetstring
      • numberstring
      • complementstring
      • neighborhoodstring
      • citystring
      • statestring

        State code with 2 letters, such as SP.

    • deliveryAddressobject
      Show child attributesHide child attributes
      • zipCodestring

        Zip code with digits only, such as 01310100.

      • streetstring
      • numberstring
      • complementstring
      • neighborhoodstring
      • citystring
      • statestring

        State code with 2 letters, such as SP.

  • expiresAtstring · date-time

    Date and time when the payment link expires. When omitted, the link does not expire.

  • maxOrdersPerLinkinteger

    Number of paid orders after which the payment link is canceled. When omitted, there is no limit.

  • supportedPaymentMethodsarray of strings

    Payment methods that the payment link presents. When omitted, all payment methods are presented. With subscription, omit it or send only credit-card.

    Possible values:credit-cardpixbank-billetcryptodebit-cardtransfer

  • subscriptionobject

    Send it to make the payment link recurring. The payment link then accepts only credit card and is saved with supportedPaymentMethods equal to ["credit-card"].

    Show child attributesHide child attributes
    • periodicitystringrequired

      Interval between recurrences. Recurrences are due every 1, 3, 6 or 12 months; the day of the month depends on when the subscription was created. See due dates.

      Possible values:MonthlyQuarterlyBiannualyAnnualy

    • repeatIndefinitelybooleanrequired

      When true, the subscription has no end and numberRecurrences must be omitted, null or 0.

    • numberRecurrencesintegernullable

      Total number of recurrences, the first one included. Required, as an integer from 1 to 1200, when repeatIndefinitely is false. When repeatIndefinitely is true, omit it or send null or 0. In responses, it is 0 when repeatIndefinitely is true.

      <= 1200

    • retryobjectnullable

      How Easyflow retries a recurrence whose charge fails or is not paid. When omitted or null, Easyflow makes up to 5 retries, 3 days apart, after the original charge, so a recurrence is charged up to 6 times while its card is not changed. When sent as an object, both fields are required.

      • Retries apply from the second recurrence on. The first recurrence is the charge made when the buyer subscribes, and it is never retried: when its order is canceled, for example because the card was refused, the subscription is canceled.
      • Change subscription credit card restarts the retries. Each delayed or failed recurrence that it sends to be charged on the new card is charged right away, its retry.retries goes back to 0 and its next retry is due intervalInDays days later. An inactive subscription becomes active again. So the number of attempts counts from the last card change, and a recurrence can be charged more times than retriesMaxNumber plus one. A recurrence retried in the last 10 minutes is not restarted.
      • The first retry is due intervalInDays days after the billingDate of the recurrence, and each following retry is due intervalInDays days after the previous one. A routine runs every 4 hours and charges the retries that are due, so a retry can happen up to 4 hours after its due time.
      • When the last retry also fails, the subscription is not canceled: its status becomes inactive and the subscription.deactivated webhook is sent. This happens when the routine runs after the next due time, about intervalInDays days after the last retry.
      Show child attributesHide child attributes
      • retriesMaxNumberintegerrequired

        Number of retries after the original charge, from 1 to 10. The original charge is not counted, so with 3 a recurrence is charged up to 4 times between card changes. Changing the card restarts the count.

        >= 1<= 10

      • intervalInDaysintegerrequired

        Days from the billingDate of the recurrence to the first retry, and from each retry to the next one, from 1 to 15.

        >= 1<= 15

Responses

200OK

OK

Content typeapplication/jsonobject

  • statusCodeinteger

    Example:200

  • dataobject
    Show child attributesHide child attributes
    • paymentLinkobject
      Show child attributesHide child attributes
      • idstring
      • createdAtstring
      • updatedAtstring
      • deletedAtstringnullable
      • deletedboolean
      • businessstring
      • checkoutstring
      • imageobject
        Show child attributesHide child attributes
        • namestringnullable
        • pathstringnullable
        • urlstringnullable
        • isPublicbooleannullable
        • extensionstringnullable
      • namestring
      • descriptionstring
      • statusstring
      • valueInCentsinteger
      • unpublishedAtstring
      • publishedAtstring
      • distUrlstring
      • preferenceobject
        Show child attributesHide child attributes
        • acceptCorporationBuyerboolean
        • acceptNaturalPersonBuyerboolean
        • requestAddressboolean
        • requestDeliveryAddressboolean
      • supportContactobject
        Show child attributesHide child attributes
        • contactEmailobject
          Show child attributesHide child attributes
          • idstring
        • namestringnullable
        • emailstringnullable
        • validatedbooleannullable
      • advancedobject
        Show child attributesHide child attributes
        • redirectobject
          Show child attributesHide child attributes
          • buttonNamestring
          • urlstring
          • delayInSecondsintegernullable
      • paymentConfigurationobject
        Show child attributesHide child attributes
        • billetobject
          Show child attributesHide child attributes
          • dueDateDelayinteger
        • pixobject
          Show child attributesHide child attributes
          • expirationInMinutesinteger
        • creditCardobject
          Show child attributesHide child attributes
          • defaultInstallmentsinteger
          • invoiceDescriptionstring
          • maxInstallmentsinteger
          • installmentOptionsarray of objects
            Show child attributesHide child attributes
            • installmentsinteger
            • installmentValueInCentsintegernullable
            • interestRateintegernullable
      • supportedPaymentMethodsarray of stringsnullable

        Payment methods that the payment link presents. null or omitted means that all payment methods are presented. It is ["credit-card"] when the payment link has subscription.

        Possible values:credit-cardpixbank-billetcryptodebit-cardtransfer

      • subscriptionobject

        Recurrence terms of the payment link. Present only when the payment link is recurring. retry is omitted when the default retry applies.

        Show child attributesHide child attributes
        • periodicitystringrequired

          Interval between recurrences. Recurrences are due every 1, 3, 6 or 12 months; the day of the month depends on when the subscription was created. See due dates.

          Possible values:MonthlyQuarterlyBiannualyAnnualy

        • repeatIndefinitelybooleanrequired

          When true, the subscription has no end and numberRecurrences must be omitted, null or 0.

        • numberRecurrencesintegernullable

          Total number of recurrences, the first one included. Required, as an integer from 1 to 1200, when repeatIndefinitely is false. When repeatIndefinitely is true, omit it or send null or 0. In responses, it is 0 when repeatIndefinitely is true.

          <= 1200

        • retryobjectnullable

          How Easyflow retries a recurrence whose charge fails or is not paid. When omitted or null, Easyflow makes up to 5 retries, 3 days apart, after the original charge, so a recurrence is charged up to 6 times while its card is not changed. When sent as an object, both fields are required.

          • Retries apply from the second recurrence on. The first recurrence is the charge made when the buyer subscribes, and it is never retried: when its order is canceled, for example because the card was refused, the subscription is canceled.
          • Change subscription credit card restarts the retries. Each delayed or failed recurrence that it sends to be charged on the new card is charged right away, its retry.retries goes back to 0 and its next retry is due intervalInDays days later. An inactive subscription becomes active again. So the number of attempts counts from the last card change, and a recurrence can be charged more times than retriesMaxNumber plus one. A recurrence retried in the last 10 minutes is not restarted.
          • The first retry is due intervalInDays days after the billingDate of the recurrence, and each following retry is due intervalInDays days after the previous one. A routine runs every 4 hours and charges the retries that are due, so a retry can happen up to 4 hours after its due time.
          • When the last retry also fails, the subscription is not canceled: its status becomes inactive and the subscription.deactivated webhook is sent. This happens when the routine runs after the next due time, about intervalInDays days after the last retry.
          Show child attributesHide child attributes
          • retriesMaxNumberintegerrequired

            Number of retries after the original charge, from 1 to 10. The original charge is not counted, so with 3 a recurrence is charged up to 4 times between card changes. Changing the card restarts the count.

            >= 1<= 10

          • intervalInDaysintegerrequired

            Days from the billingDate of the recurrence to the first retry, and from each retry to the next one, from 1 to 15.

            >= 1<= 15

400If the provided parameter is invalid, the API will return the following error response:

If the provided parameter is invalid, the API will return the following error response:

Content typeapplication/jsonobject

  • messagestring

    Invalid param: []

    Example:Invalid param: []

  • errorstring

    Bad Request

    Example:Bad Request

  • statusCodeinteger

    400

    Example:400

  • errorCodestring

    Code that identifies the error. Present only on some errors.

401The credential is missing or invalid, the request does not send the business identifier (message BusinessId is required), or it sends business-id and x-business-id with different values.

The credential is missing or invalid, the request does not send the business identifier (message BusinessId is required), or it sends business-id and x-business-id with different values.

Content typeapplication/jsonobject

  • messagestring

    Invalid field

    Example:Unauthorized

  • errorstring

    Unauthorized

    Example:Unauthorized

  • statusCodeinteger

    401

    Example:401

403The user of the API key is not a collaborator of the business sent in business-id or x-business-id, a seller of an active sales team of that business, or an Easyflow platform administrator.

The user of the API key is not a collaborator of the business sent in business-id or x-business-id, a seller of an active sales team of that business, or an Easyflow platform administrator.

Content typeapplication/jsonobject

  • messagestring

    Forbidden resource

    Example:Forbidden resource

  • errorstring

    Forbidden

    Example:Forbidden

  • statusCodeinteger

    403

    Example:403

500If an unexpected condition occurs and the server cannot process the request, the API will return the following error response. This response has no error field.

If an unexpected condition occurs and the server cannot process the request, the API will return the following error response. This response has no error field.

Content typeapplication/jsonobject

  • statusCodeinteger

    HTTP status code.

    Example:500

  • messagestring

    Explanation of the error.

    Example:Internal Server Error