Api key provided on integrations tab in Easyflow platform.
Create payment link
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
subscriptionto 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 sendssubscription.created, and, if the first order is refused, the subscription is canceled and Easyflow sendssubscription.canceled. The payment link is saved withsupportedPaymentMethodsequal to["credit-card"]. - With
subscription,valueInCentsmust be an integer equal to or greater than the minimum charge value of the platform (by default, 1000). Otherwise the API returns400withInvalid param: [valueInCents]anderrorCodePAYMENT_LINK_SUBSCRIPTION_BELOW_MINIMUM_VALUE. - With
subscription,supportedPaymentMethodsmust be omitted or contain onlycredit-card. A list with another method,nullor an empty list returns400withInvalid param: [supportedPaymentMethods]anderrorCodePAYMENT_LINK_SUBSCRIPTION_CREDIT_CARD_ONLY. - An invalid field of
subscriptionreturns400with the field name prefixed bysubscription., such asMissing param: [subscription.periodicity],Invalid param: [subscription.numberRecurrences]orInvalid 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-keystringrequiredx-api-secretstringrequiredApi Secret provided on integrations tab in Easyflow platform.
business-idstringrequiredIdentifier 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
400withInvalid param: [businessId], a business that the user is not linked to returns403, and a request that also sendsx-business-idwith a different value returns401.
Request body
Content typeapplication/jsonobject
namestringrequireddescriptionstringrequiredvalueInCentsintegerrequiredValue of the payment link in cents. Must be greater than zero.
checkoutTemplateIdstring · uuidID of the checkout template. When omitted, the default checkout template of the business is used.
preferenceobjectData that the checkout of the payment link asks from the buyer.
Show child attributesHide child attributes
acceptNaturalPersonBuyerbooleanacceptCorporationBuyerbooleanrequestAddressbooleanrequestDeliveryAddressbooleanrequireEmailReentrybooleandisableCouponFormboolean
paymentConfigurationobjectShow child attributesHide child attributes
billetobjectShow child attributesHide child attributes
dueDateDelayinteger
pixobjectShow child attributesHide child attributes
expirationInMinutesinteger
creditCardobjectShow child attributesHide child attributes
defaultInstallmentsintegermaxInstallmentsintegerinvoiceDescriptionstringinstallmentOptionsarray of objectsShow child attributesHide child attributes
installmentsintegerinstallmentValueInCentsintegernullableinterestRateintegernullable
supportContactobjectSupport contact shown to the buyer. When omitted, the default contact email of the business is used.
Show child attributesHide child attributes
contactEmailIdstring · uuidrequiredID of a validated contact email of the business.
advancedobjectShow child attributesHide child attributes
redirectobjectRedirect shown to the buyer after the payment.
Show child attributesHide child attributes
urlstringbuttonNamestringdelayInSecondsintegernullable
buyerWhitelistobjectShow child attributesHide child attributes
emailDomainsarray of stringsEmail domains allowed to buy with the payment link, such as
example.com. Empty or omitted means that any email can buy.
interestSettingsobjectShow child attributesHide child attributes
sellerAbsorbsInterestbooleanrequiredWhen
true, the seller absorbs the installment interest and every installment option has an interest rate of 0.
payerobjectData of the payer of the payment link.
Show child attributesHide child attributes
namestringrequiredemailstringrequireddocumentobjectrequiredShow child attributesHide child attributes
typestringrequirednumberstringrequiredDocument number with digits only.
phoneobjectShow child attributesHide child attributes
areaCodestringdddstringnumberstringisMobileboolean
addressobjectShow child attributesHide child attributes
zipCodestringZip code with digits only, such as
01310100.streetstringnumberstringcomplementstringneighborhoodstringcitystringstatestringState code with 2 letters, such as
SP.
deliveryAddressobjectShow child attributesHide child attributes
zipCodestringZip code with digits only, such as
01310100.streetstringnumberstringcomplementstringneighborhoodstringcitystringstatestringState code with 2 letters, such as
SP.
expiresAtstring · date-timeDate and time when the payment link expires. When omitted, the link does not expire.
maxOrdersPerLinkintegerNumber of paid orders after which the payment link is canceled. When omitted, there is no limit.
supportedPaymentMethodsarray of stringsPayment methods that the payment link presents. When omitted, all payment methods are presented. With
subscription, omit it or send onlycredit-card.subscriptionobjectSend it to make the payment link recurring. The payment link then accepts only credit card and is saved with
supportedPaymentMethodsequal to["credit-card"].Show child attributesHide child attributes
periodicitystringrequiredInterval 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.
repeatIndefinitelybooleanrequiredWhen
true, the subscription has no end andnumberRecurrencesmust be omitted,nullor0.numberRecurrencesintegernullableTotal number of recurrences, the first one included. Required, as an integer from 1 to 1200, when
repeatIndefinitelyisfalse. WhenrepeatIndefinitelyistrue, omit it or sendnullor0. In responses, it is0whenrepeatIndefinitelyistrue.retryobjectnullableHow 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
delayedorfailedrecurrence that it sends to be charged on the new card is charged right away, itsretry.retriesgoes back to0and its next retry is dueintervalInDaysdays later. Aninactivesubscription becomesactiveagain. So the number of attempts counts from the last card change, and a recurrence can be charged more times thanretriesMaxNumberplus one. A recurrence retried in the last 10 minutes is not restarted. - The first retry is due
intervalInDaysdays after thebillingDateof the recurrence, and each following retry is dueintervalInDaysdays 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
statusbecomesinactiveand thesubscription.deactivatedwebhook is sent. This happens when the routine runs after the next due time, aboutintervalInDaysdays after the last retry.
Show child attributesHide child attributes
retriesMaxNumberintegerrequiredNumber of retries after the original charge, from 1 to 10. The original charge is not counted, so with
3a recurrence is charged up to 4 times between card changes. Changing the card restarts the count.intervalInDaysintegerrequiredDays from the
billingDateof the recurrence to the first retry, and from each retry to the next one, from 1 to 15.
Responses
200OK
OK
Content typeapplication/jsonobject
statusCodeintegerdataobjectShow child attributesHide child attributes
paymentLinkobjectShow child attributesHide child attributes
idstringcreatedAtstringupdatedAtstringdeletedAtstringnullabledeletedbooleanbusinessstringcheckoutstringimageobjectShow child attributesHide child attributes
namestringnullablepathstringnullableurlstringnullableisPublicbooleannullableextensionstringnullable
namestringdescriptionstringstatusstringvalueInCentsintegerunpublishedAtstringpublishedAtstringdistUrlstringpreferenceobjectShow child attributesHide child attributes
acceptCorporationBuyerbooleanacceptNaturalPersonBuyerbooleanrequestAddressbooleanrequestDeliveryAddressboolean
supportContactobjectShow child attributesHide child attributes
contactEmailobjectShow child attributesHide child attributes
idstring
namestringnullableemailstringnullablevalidatedbooleannullable
advancedobjectShow child attributesHide child attributes
redirectobjectShow child attributesHide child attributes
buttonNamestringurlstringdelayInSecondsintegernullable
paymentConfigurationobjectShow child attributesHide child attributes
billetobjectShow child attributesHide child attributes
dueDateDelayinteger
pixobjectShow child attributesHide child attributes
expirationInMinutesinteger
creditCardobjectShow child attributesHide child attributes
defaultInstallmentsintegerinvoiceDescriptionstringmaxInstallmentsintegerinstallmentOptionsarray of objectsShow child attributesHide child attributes
installmentsintegerinstallmentValueInCentsintegernullableinterestRateintegernullable
supportedPaymentMethodsarray of stringsnullablePayment methods that the payment link presents.
nullor omitted means that all payment methods are presented. It is["credit-card"]when the payment link hassubscription.subscriptionobjectRecurrence terms of the payment link. Present only when the payment link is recurring.
retryis omitted when the default retry applies.Show child attributesHide child attributes
periodicitystringrequiredInterval 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.
repeatIndefinitelybooleanrequiredWhen
true, the subscription has no end andnumberRecurrencesmust be omitted,nullor0.numberRecurrencesintegernullableTotal number of recurrences, the first one included. Required, as an integer from 1 to 1200, when
repeatIndefinitelyisfalse. WhenrepeatIndefinitelyistrue, omit it or sendnullor0. In responses, it is0whenrepeatIndefinitelyistrue.retryobjectnullableHow 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
delayedorfailedrecurrence that it sends to be charged on the new card is charged right away, itsretry.retriesgoes back to0and its next retry is dueintervalInDaysdays later. Aninactivesubscription becomesactiveagain. So the number of attempts counts from the last card change, and a recurrence can be charged more times thanretriesMaxNumberplus one. A recurrence retried in the last 10 minutes is not restarted. - The first retry is due
intervalInDaysdays after thebillingDateof the recurrence, and each following retry is dueintervalInDaysdays 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
statusbecomesinactiveand thesubscription.deactivatedwebhook is sent. This happens when the routine runs after the next due time, aboutintervalInDaysdays after the last retry.
Show child attributesHide child attributes
retriesMaxNumberintegerrequiredNumber of retries after the original charge, from 1 to 10. The original charge is not counted, so with
3a recurrence is charged up to 4 times between card changes. Changing the card restarts the count.intervalInDaysintegerrequiredDays from the
billingDateof the recurrence to the first retry, and from each retry to the next one, from 1 to 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
messagestringInvalid param: []
errorstringBad Request
statusCodeinteger400
errorCodestringCode 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
messagestringInvalid field
errorstringUnauthorized
statusCodeinteger401
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
messagestringForbidden resource
errorstringForbidden
statusCodeinteger403
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
statusCodeintegerHTTP status code.
messagestringExplanation of the error.