Create payment link
Create a payment link that allows an end user to make a payment on Moov's hosted payment link page.
To access this endpoint using an access token
you'll need to specify the /accounts/{accountID}/transfers.write scope.
curl -X POST "https://api.moov.io/accounts/{accountID}/payment-links" \
-H "Authorization: Bearer {token}" \
-H "x-moov-version: v2024.01.00" \
--data-raw '{
"accountID": "c197cd40-7745-4413-8f3b-ec962d1b5225",
"merchantPaymentMethodID": "3afc7533-7095-43bb-b21a-5c4dc5568451",
"partnerAccountID": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"amount": {
"currency": "USD",
"value": 1204
},
"maxUses": 0,
"expiresOn": "2025-08-24T14:15:22Z",
"display": {
"title": "string",
"description": "string",
"callToAction": "pay"
},
"customer": {
"requireAddress": true,
"requirePhone": true,
"metadata": {
"property1": "string",
"property2": "string"
}
},
"payment": {
"allowedMethods": [
"apple-pay",
"card-payment",
"ach-debit-collect"
],
"cardDetails": {
"dynamicDescriptor": "WhlBdy *Yoga 11-12"
},
"achDetails": {
"companyEntryDescription": "Gym Dues",
"originatingCompanyName": "Whole Body Fit"
}
}
}'\
import { SDK } from "openapi";
const sdk = new SDK({
xMoovVersion: "v2024.01.00",
});
async function run() {
const result = await sdk.paymentLinks.create({
accountID: "cc1d04a8-03b1-4600-b675-e6180d574074",
createPaymentLink: {
partnerAccountID: "d290f1ee-6c54-4b01-90e6-d701748f0851",
merchantPaymentMethodID: "4c4e7f8e-81f4-4f3d-8f6f-6f6e7f8e4c4e",
amount: {
currency: "USD",
value: 10000,
},
display: {
title: "Example Payment Link",
description: "This is an example payment link.",
callToAction: "pay",
},
customer: {
requirePhone: true,
},
payment: {
allowedMethods: [
"card-payment",
"ach-debit-collect",
],
},
},
});
console.log(result);
}
run();declare(strict_types=1);
require 'vendor/autoload.php';
use OpenAPI\OpenAPI;
use OpenAPI\OpenAPI\Models\Components;
$sdk = OpenAPI\SDK::builder()
->setXMoovVersion('v2024.01.00')
->build();
$createPaymentLink = new Components\CreatePaymentLink(
partnerAccountID: 'd290f1ee-6c54-4b01-90e6-d701748f0851',
merchantPaymentMethodID: '4c4e7f8e-81f4-4f3d-8f6f-6f6e7f8e4c4e',
amount: new Components\Amount(
currency: 'USD',
value: 10000,
),
display: new Components\PaymentLinkDisplayOptions(
title: 'Example Payment Link',
description: 'This is an example payment link.',
callToAction: Components\CallToAction::Pay,
),
customer: new Components\PaymentLinkCustomerOptions(
requirePhone: true,
),
payment: new Components\PaymentLinkPaymentDetails(
allowedMethods: [
Components\CollectionPaymentMethodType::CardPayment,
Components\CollectionPaymentMethodType::AchDebitCollect,
],
),
);
$response = $sdk->paymentLinks->create(
accountID: 'cc1d04a8-03b1-4600-b675-e6180d574074',
createPaymentLink: $createPaymentLink
);
if ($response->paymentLink !== null) {
// handle response
}from openapi import SDK
with SDK(
x_moov_version="v2024.01.00",
) as sdk:
res = sdk.payment_links.create(account_id="cc1d04a8-03b1-4600-b675-e6180d574074", partner_account_id="d290f1ee-6c54-4b01-90e6-d701748f0851", merchant_payment_method_id="4c4e7f8e-81f4-4f3d-8f6f-6f6e7f8e4c4e", amount={
"currency": "USD",
"value": 10000,
}, display={
"title": "Example Payment Link",
"description": "This is an example payment link.",
"call_to_action": "pay",
}, customer={
"require_phone": True,
}, payment={
"allowed_methods": [
"card-payment",
"ach-debit-collect",
],
}, payout={
"allowed_methods": [
"ach-credit-standard",
],
"recipient": {
"email": "jordan.lee@classbooker.dev",
"phone": {
"number": "8185551212",
"country_code": "1",
},
},
})
# Handle response
print(res)package hello.world;
import java.lang.Exception;
import java.util.List;
import org.openapis.openapi.SDK;
import org.openapis.openapi.models.components.*;
import org.openapis.openapi.models.errors.CreatePaymentLinkError;
import org.openapis.openapi.models.errors.GenericError;
import org.openapis.openapi.models.operations.CreatePaymentLinkResponse;
public class Application {
public static void main(String[] args) throws GenericError, CreatePaymentLinkError, Exception {
SDK sdk = SDK.builder()
.xMoovVersion("v2024.01.00")
.build();
CreatePaymentLinkResponse res = sdk.paymentLinks().create()
.accountID("cc1d04a8-03b1-4600-b675-e6180d574074")
.createPaymentLink(CreatePaymentLink.builder()
.partnerAccountID("d290f1ee-6c54-4b01-90e6-d701748f0851")
.merchantPaymentMethodID("4c4e7f8e-81f4-4f3d-8f6f-6f6e7f8e4c4e")
.amount(Amount.builder()
.currency("USD")
.value(10000L)
.build())
.display(PaymentLinkDisplayOptions.builder()
.title("Example Payment Link")
.description("This is an example payment link.")
.callToAction(CallToAction.PAY)
.build())
.customer(PaymentLinkCustomerOptions.builder()
.requirePhone(true)
.build())
.payment(PaymentLinkPaymentDetails.builder()
.allowedMethods(List.of(
CollectionPaymentMethodType.CARD_PAYMENT,
CollectionPaymentMethodType.ACH_DEBIT_COLLECT))
.build())
.build())
.call();
if (res.paymentLink().isPresent()) {
// handle response
}
}
}require 'openapi'
Models = ::OpenApiSDK::Models
s = ::OpenApiSDK::SDK.new(
x_moov_version: 'v2024.01.00',
)
res = s.payment_links.create(account_id: 'cc1d04a8-03b1-4600-b675-e6180d574074', create_payment_link: Models::Components::CreatePaymentLink.new(
partner_account_id: 'd290f1ee-6c54-4b01-90e6-d701748f0851',
merchant_payment_method_id: '4c4e7f8e-81f4-4f3d-8f6f-6f6e7f8e4c4e',
amount: Models::Components::Amount.new(
currency: 'USD',
value: 10_000,
),
display: Models::Components::PaymentLinkDisplayOptions.new(
title: 'Example Payment Link',
description: 'This is an example payment link.',
call_to_action: Models::Components::CallToAction::PAY,
),
customer: Models::Components::PaymentLinkCustomerOptions.new(
require_phone: true,
),
payment: Models::Components::PaymentLinkPaymentDetails.new(
allowed_methods: [
Models::Components::CollectionPaymentMethodType::CARD_PAYMENT,
Models::Components::CollectionPaymentMethodType::ACH_DEBIT_COLLECT,
],
),
))
unless res.payment_link.nil?
# handle response
end{
"amount": {
"currency": "USD",
"value": 10000
},
"code": "3QLHtONjd5",
"createdOn": "2025-01-09T17:09:13.33Z",
"customer": {
"requirePhone": true
},
"display": {
"callToAction": "pay",
"description": "This is an example payment link.",
"title": "Example Payment Link"
},
"link": "https://moov.link/p/3QLHtONjd5",
"merchantAccountID": "34233b72-780c-4e0e-8b08-cbbe1bc878f8",
"merchantPaymentMethodID": "4c4e7f8e-81f4-4f3d-8f6f-6f6e7f8e4c4e",
"mode": "sandbox",
"ownerAccountID": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"partnerAccountID": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"payment": {
"allowedMethods": [
"card-payment",
"ach-debit-collect"
]
},
"paymentLinkType": "payment",
"status": "active",
"updatedOn": "2025-01-09T17:09:13.33Z",
"uses": 0
}Response headers
x-request-id
string
required
{
"error": "string"
}Response headers
x-request-id
string
required
Response headers
x-request-id
string
required
Response headers
x-request-id
string
required
Response headers
x-request-id
string
required
{
"error": "string"
}Response headers
x-request-id
string
required
{
"partnerAccountID": "string",
"merchantPaymentMethodID": "string",
"amount": {
"currency": "string",
"value": "string"
},
"salesTaxAmount": {
"currency": "string",
"value": "string"
},
"maxUses": "string",
"expiresOn": "string",
"display": {
"title": "string",
"description": "string",
"callToAction": "string"
},
"payment": {
"allowedMethods": "string",
"cardDetails": {
"dynamicDescriptor": "string"
},
"achDetails": {
"companyEntryDescription": "string",
"originatingCompanyName": "string"
},
"metadata": "string"
},
"payout": {
"allowedMethods": "string",
"recipient": {
"email": "string",
"phone": {
"number": "string",
"countryCode": "string"
}
},
"metadata": "string"
},
"lineItems": {
"items": {
"property1": {
"productID": "string",
"name": "string",
"basePrice": {
"currency": "string",
"valueDecimal": "string"
},
"options": {
"property1": {
"name": "string",
"group": "string",
"priceModifier": {
"currency": "string",
"valueDecimal": "string"
},
"quantity": "string"
},
"property2": {
"name": "string",
"group": "string",
"priceModifier": {
"currency": "string",
"valueDecimal": "string"
},
"quantity": "string"
}
},
"quantity": "string"
},
"property2": {
"productID": "string",
"name": "string",
"basePrice": {
"currency": "string",
"valueDecimal": "string"
},
"options": {
"property1": {
"name": "string",
"group": "string",
"priceModifier": {
"currency": "string",
"valueDecimal": "string"
},
"quantity": "string"
},
"property2": {
"name": "string",
"group": "string",
"priceModifier": {
"currency": "string",
"valueDecimal": "string"
},
"quantity": "string"
}
},
"quantity": "string"
}
}
}
}Response headers
x-request-id
string
required
Response headers
x-request-id
string
required
Response headers
x-request-id
string
required
Response headers
x-request-id
string
required
Headers
X-Moov-Version
string
Specify an API version.
API versioning follows the format vYYYY.QQ.BB, where
YYYYis the yearQQis the two-digit month for the first month of the quarter (e.g., 01, 04, 07, 10)BBis the build number, starting at.01, for subsequent builds in the same quarter.- For example,
v2024.01.00is the initial release of the first quarter of 2024.
- For example,
The dev version represents the most recent development state. It may include breaking changes and should be treated as a beta release.
When no version is specified, the API defaults to v2024.01.00.
Path parameters
accountID
string
required
Body
Request to create a new payment link.
A payment link must include either payment or payout details, but not both. For payout payment links,
maxUses will automatically be set to 1, as these are intended for a one-time disbursement
to a specific recipient.
amount
object
required
Show child attributes
currency
string
required
Pattern
value
integer<int64>
required
Quantity in the smallest unit of the specified currency.
In USD this is cents, for example, $12.04 is 1204 and $0.99 is 99.
display
object
required
Show child attributes
callToAction
string<enum>
required
The text to be displayed on web form's submit button.
If set to "auto" the UI will automatically select between "pay" and "confirm" for payments and payouts respectively.
pay,
book,
subscribe,
donate,
confirm,
auto
description
string
required
title
string
required
merchantPaymentMethodID
string
required
partnerAccountID
string
required
customer
object
Show child attributes
metadata
object
requireAddress
boolean
requirePhone
boolean
expiresOn
string<date-time>
lineItems
object
Show child attributes
items
array<object>
required
Show child attributes
basePrice
object
Show child attributes
currency
string
required
Pattern
valueDecimal
string
required
Pattern
A decimal-formatted numerical string that represents up to 9 decimal place precision.
For example, $12.987654321 is '12.987654321'.
imageIDs
array<string>
deprecated
name
string
[1 to 150] characters
options
array<object>
Show child attributes
group
string
<=100 characters
imageIDs
array<string>
deprecated
Optional list of images associated with this line item option.
This field is deprecated and will be ignored. A future release will populate images associated with the given productID.
name
string
[1 to 150] characters
priceModifier
object
Show child attributes
currency
string
required
Pattern
valueDecimal
string
required
Pattern
A decimal-formatted numerical string that represents up to 9 decimal place precision.
For example, $12.987654321 is '12.987654321'.
quantity
integer<int32>
productID
string
quantity
integer<int32>
maxUses
integer<int64>
An optional limit on the number of times this payment link can be used.
For payouts, maxUses is always 1.
payment
object
Show child attributes
allowedMethods
array<string>
required
apple-pay,
card-payment,
ach-debit-collect
achDetails
object
Show child attributes
companyEntryDescription
string
[4 to 10] characters
originatingCompanyName
string
[4 to 16] characters
cardDetails
object
Show child attributes
dynamicDescriptor
string
[4 to 22] characters
metadata
object
payout
object
Show child attributes
allowedMethods
array<string>
required
push-to-card,
rtp-credit,
ach-credit-same-day,
ach-credit-standard
recipient
object
required
Specify the intended recipient of the payout.
Either email or phone must be specified, but not both.
This information will be used to authenticate the end user when they follow the payment link.
Show child attributes
string<email>
<=255 characters
phone
object
Show child attributes
countryCode
string
<=1 characters
number
string
<=10 characters
metadata
object
salesTaxAmount
object
Show child attributes
currency
string
required
Pattern
value
integer<int64>
required
Quantity in the smallest unit of the specified currency.
In USD this is cents, for example, $12.04 is 1204 and $0.99 is 99.
Response
amount
object
required
Show child attributes
currency
string
required
Pattern
value
integer<int64>
required
Quantity in the smallest unit of the specified currency.
In USD this is cents, for example, $12.04 is 1204 and $0.99 is 99.
code
string
required
createdOn
string<date-time>
required
customer
object
required
Show child attributes
metadata
object
requireAddress
boolean
requirePhone
boolean
display
object
required
Show child attributes
callToAction
string<enum>
required
The text to be displayed on web form's submit button.
If set to "auto" the UI will automatically select between "pay" and "confirm" for payments and payouts respectively.
pay,
book,
subscribe,
donate,
confirm,
auto
description
string
required
title
string
required
link
string<uri>
required
merchantAccountID
string
required
merchantPaymentMethodID
string
required
mode
string<enum>
required
sandbox,
production
ownerAccountID
string
required
partnerAccountID
string
required
paymentLinkType
string<enum>
required
payment,
payout,
invoice-payment
status
string<enum>
required
active,
used,
disabled,
expired
updatedOn
string<date-time>
required
uses
integer<int64>
required
disabledOn
string<date-time>
expiresOn
string<date-time>
lastUsedOn
string<date-time>
lineItems
object
Show child attributes
items
array<object>
required
Show child attributes
basePrice
object
Show child attributes
currency
string
required
Pattern
valueDecimal
string
required
Pattern
A decimal-formatted numerical string that represents up to 9 decimal place precision.
For example, $12.987654321 is '12.987654321'.
images
array<object>
Show child attributes
altText
string
<=125 characters
imageID
string
link
string<uri>
publicID
string
Pattern
name
string
[1 to 150] characters
options
array<object>
Show child attributes
group
string
<=100 characters
images
array<object>
Show child attributes
altText
string
<=125 characters
imageID
string
link
string<uri>
publicID
string
Pattern
name
string
[1 to 150] characters
priceModifier
object
Show child attributes
currency
string
required
Pattern
valueDecimal
string
required
Pattern
A decimal-formatted numerical string that represents up to 9 decimal place precision.
For example, $12.987654321 is '12.987654321'.
quantity
integer<int32>
productID
string
quantity
integer<int32>
maxUses
integer<int64>
An optional limit on the number of times this payment link can be used.
For payouts, maxUses is always 1.
payment
object
Show child attributes
allowedMethods
array<string>
required
apple-pay,
card-payment,
ach-debit-collect
achDetails
object
Show child attributes
companyEntryDescription
string
[4 to 10] characters
originatingCompanyName
string
[4 to 16] characters
cardDetails
object
Show child attributes
dynamicDescriptor
string
[4 to 22] characters
metadata
object
payout
object
Show child attributes
allowedMethods
array<string>
required
push-to-card,
rtp-credit,
ach-credit-same-day,
ach-credit-standard
recipient
object
required
Specify the intended recipient of the payout.
Either email or phone must be specified, but not both.
This information will be used to authenticate the end user when they follow the payment link.
Show child attributes
string<email>
<=255 characters
phone
object
Show child attributes
countryCode
string
<=1 characters
number
string
<=10 characters
metadata
object
salesTaxAmount
object
Show child attributes
currency
string
required
Pattern
value
integer<int64>
required
Quantity in the smallest unit of the specified currency.
In USD this is cents, for example, $12.04 is 1204 and $0.99 is 99.