Afterpay Grants API

{"openapi":"3.1.0","info":{"title":"Grants - Afterpay","version":"1.0.0"},"paths":{"/v2/grants/approvals":{"post":{"operationId":"start-grant-approval","summary":"Create Grant Approval","description":"Initiates the approval process for a new grant.\n","tags":[""],"parameters":[{"name":"Authorization","in":"header","description":"Basic authentication","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","required":false,"schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantApprovalResponse"}}}},"401":{"description":"Authentication failed or insufficient permissions.\n\n| errorCode | Description |\n| --- | --- |\n| unauthorized | The API credentials are invalid or missing. |\n| insufficient_permissions | The merchant lacks the required 'merchant_api_v2/initiate' permission. |\n","content":{"application/json":{"schema":{"description":"Any type"}}}},"403":{"description":"| errorCode | Description |\n| --- | --- |\n| feature_not_enabled | On file payments are not enabled for this merchant. |\n","content":{"application/json":{"schema":{"description":"Any type"}}}},"415":{"description":"Unsupported Media Type - Content-Type header is missing or invalid","content":{"application/json":{"schema":{"description":"Any type"}}}},"422":{"description":"| errorCode | Description |\n| --- | --- |\n| invalid_object | One or more required fields in the request body were missing or invalid. |\n","content":{"application/json":{"schema":{"description":"Any type"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantApprovalRequest"}}}}}},"/v2/grants":{"post":{"operationId":"create-grant","summary":"Create Grant","description":"Creates a new grant from a grant approval token. \n","tags":[""],"parameters":[{"name":"Authorization","in":"header","description":"Basic authentication","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","required":false,"schema":{"type":"string","default":"application/json"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantResponse"}}}},"403":{"description":"| errorCode | Description |\n| --- | --- |\n| feature_not_enabled | On file payments are not enabled for this merchant. |\n","content":{"application/json":{"schema":{"description":"Any type"}}}},"412":{"description":"| errorCode | Description |\n| --- | --- |\n| consumer_ineligible | Consumer not eligible |\n","content":{"application/json":{"schema":{"description":"Any type"}}}},"415":{"description":"Unsupported Media Type - Content-Type header is missing or invalid","content":{"application/json":{"schema":{"description":"Any type"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGrantRequest"}}}}}},"/v2/grants/{grantId}":{"get":{"operationId":"get-grant","summary":"Retrieve Grant","description":"Retrieves a grant by its ID.\n","tags":[""],"parameters":[{"name":"grantId","in":"path","description":"ID of the grant to retrieve.","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Basic authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantResponse"}}}},"403":{"description":"| errorCode | Description |\n| --- | --- |\n| feature_not_enabled | On file payments are not enabled for this merchant. |\n","content":{"application/json":{"schema":{"description":"Any type"}}}},"404":{"description":"| errorCode | Description |\n| --- | --- |\n| grant_not_found | The specified grant id was not found. |\n","content":{"application/json":{"schema":{"description":"Any type"}}}}}}},"/v2/grants/{grantId}/revoke":{"post":{"operationId":"revoke-grant","summary":"Revoke Grant","description":"Revokes a grant, rendering it unusable. Other endpoints will no longer be able to use the grant to perform its associated action.\n","tags":[""],"parameters":[{"name":"grantId","in":"path","description":"The unique identifier id of the grant to revoke","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Basic authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantResponse"}}}},"403":{"description":"| errorCode | Description |\n| --- | --- |\n| feature_not_enabled | On file payments are not enabled for this merchant. |\n","content":{"application/json":{"schema":{"description":"Any type"}}}},"404":{"description":"| errorCode | Description |\n| --- | --- |\n| grant_not_found | The specified grant was not found. |\n","content":{"application/json":{"schema":{"description":"Any type"}}}}}}},"/v2/grants/alias":{"post":{"operationId":"alias-grant","summary":"Create Grant Alias","description":"Creates an alias for an existing grant to help load the payment schedule widget.\n","tags":[""],"parameters":[{"name":"Authorization","in":"header","description":"Basic authentication","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","required":false,"schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantAliasResponse"}}}},"403":{"description":"| errorCode | Description |\n| --- | --- |\n| feature_not_enabled | On file payments are not enabled for this merchant. |\n","content":{"application/json":{"schema":{"description":"Any type"}}}},"415":{"description":"Unsupported Media Type - Content-Type header is missing or invalid","content":{"application/json":{"schema":{"description":"Any type"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantAliasRequest"}}}}}},"/v2/grants/start":{"post":{"operationId":"start-billing-agreement-link","summary":"Start Grant Link Flow","description":"Initiates the headless grant link flow process.\n","tags":[""],"parameters":[{"name":"Authorization","in":"header","description":"Basic authentication","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","required":false,"schema":{"type":"string","default":"application/json"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantStartResponse"}}}},"404":{"description":"| errorCode | Description |\n| --- | --- |\n| not_found | Afterpay consumer account does not exist |\n","content":{"application/json":{"schema":{"description":"Any type"}}}},"412":{"description":"| errorCode | Description |\n| --- | --- |\n| invalid_state | Failed to send code |\n","content":{"application/json":{"schema":{"description":"Any type"}}}},"429":{"description":"| errorCode | Description |\n| --- | --- |\n| too_many_requests | Too many requests |\n","content":{"application/json":{"schema":{"description":"Any type"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantStartRequest"}}}}}}},"servers":[{"url":"https://global-api-sandbox.afterpay.com","description":"Sandbox"},{"url":"https://global-api.afterpay.com","description":"Production"}],"webhooks":{"grant-status-updated":{"post":{"operationId":"grant-status-updated","summary":"Grant status updated","description":"Webhook notification sent when a grant's status changes","responses":{"200":{"description":"Webhook received successfully"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnFileGrantStatusUpdated"}}}}}}},"components":{"schemas":{"GrantApprovalTypeType":{"type":"string","enum":["ON_FILE"],"description":"Grant Type for approval.","title":"GrantApprovalTypeType"},"GrantApprovalType":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/GrantApprovalTypeType","description":"Grant Type for approval."},"merchantReference":{"type":["string","null"],"description":"A merchant-provided reference for the grant."}},"required":["type"],"description":"Details about the grant to be created.","title":"GrantApprovalType"},"GrantApprovalRequestMerchant":{"type":"object","properties":{"redirectConfirmUrl":{"type":"string"},"redirectCancelUrl":{"type":"string"},"popupOriginUrl":{"type":"string","description":"This property is optional when a `redirectConfirmURL` is provided."},"name":{"type":"string","description":"The merchant name displayed in the Afterpay approval flow."}},"required":["redirectConfirmUrl","redirectCancelUrl"],"title":"GrantApprovalRequestMerchant"},"Consumer":{"type":"object","properties":{"email":{"type":"string","format":"email"},"givenNames":{"type":"string","description":"The consumer's first name"},"surname":{"type":"string","description":"The consumer's last name"},"phoneNumber":{"type":"string"}},"required":["email"],"description":"The consumer data model is used for gathering essential user information. It captures details such as the individual's first name, represented by `givenNames`, and their last name, captured under `surname`. In addition, it stores the user's contact number under `phoneNumber` and their email address under `email`. These fields collectively provide contact and identification details for a user.","title":"Consumer"},"GrantApprovalRequest":{"type":"object","properties":{"grants":{"type":"array","items":{"$ref":"#/components/schemas/GrantApprovalType"},"description":"Grant type for approval (only single grant is supported)"},"merchant":{"$ref":"#/components/schemas/GrantApprovalRequestMerchant"},"consumer":{"$ref":"#/components/schemas/Consumer","description":"Consumer details for the grant"}},"required":["grants","merchant"],"title":"GrantApprovalRequest"},"GrantApprovalResponse":{"type":"object","properties":{"token":{"type":"string","description":"Token identifying this grant approval request"},"expires":{"type":"string","format":"date-time","description":"When this approval request expires"},"redirectCheckoutUrl":{"type":"string","format":"uri","description":"URL where the consumer should be redirected to complete approval"}},"required":["token","expires","redirectCheckoutUrl"],"title":"GrantApprovalResponse"},"CreateGrantRequest":{"type":"object","properties":{"requestId":{"type":"string","description":"A unique request ID, required for idempotent retries. It is recommended that the merchant generate a UUID for each unique request."},"token":{"type":"string","description":"The token returned from the create approval request."},"code":{"type":"string","description":"The one-time code received from the consumer.\nNote: The code will only be sent with the headless integration."}},"required":["requestId","token"],"title":"CreateGrantRequest"},"GrantType":{"type":"string","enum":["ON_FILE"],"description":"Type of grant","title":"GrantType"},"GrantStatus":{"type":"string","enum":["ACTIVE","CANCELLED"],"description":"Current status of the grant","title":"GrantStatus"},"Grant":{"type":"object","properties":{"id":{"type":"string","description":"Unique id identifying the grant"},"type":{"$ref":"#/components/schemas/GrantType","description":"Type of grant"},"status":{"$ref":"#/components/schemas/GrantStatus","description":"Current status of the grant"},"created":{"type":"string","format":"date-time","description":"Timestamp when the grant was created"},"merchantReference":{"type":["string","null"],"description":"Merchant's reference for this grant"},"cancelled":{"type":"string","format":"date-time","description":"If present, indicates when the grant was cancelled"},"expires":{"type":"string","format":"date-time","description":"If present, indicates when the grant's status will become EXPIRED, preventing a client from using it to create payments"},"consumerReference":{"type":["string","null"],"description":"Reference identifier for the consumer"},"email":{"type":["string","null"],"description":"Masked email address of the consumer"},"requestId":{"type":["string","null"],"description":"If present, unique identifier for the request"}},"required":["id","type","status","created"],"title":"Grant"},"GrantResponse":{"type":"object","properties":{"grant":{"$ref":"#/components/schemas/Grant"}},"required":["grant"],"title":"GrantResponse"},"GrantAliasRequest":{"type":"object","properties":{"token":{"type":"string","description":"Token of the grant to create an alias for"},"duration":{"type":["string","null"],"format":"duration","description":"Duration of the grant in ISO-8601 period format"}},"required":["token"],"title":"GrantAliasRequest"},"GrantAliasResponse":{"type":"object","properties":{"token":{"type":"string","description":"Token representing the grant alias"},"expiry":{"type":"string","format":"date-time","description":"Timestamp when the alias token expires"}},"required":["token","expiry"],"title":"GrantAliasResponse"},"GrantStartRequest":{"type":"object","properties":{"alias":{"type":"string","description":"Email or phone number associated with the consumer's account"},"requestId":{"type":"string","description":"A unique identifier for this request"}},"required":["alias","requestId"],"title":"GrantStartRequest"},"GrantStartResponseDeliveryType":{"type":"string","enum":["SMS","EMAIL"],"description":"How the verification code was delivered to the consumer","title":"GrantStartResponseDeliveryType"},"GrantStartResponse":{"type":"object","properties":{"token":{"type":"string","description":"Token identifying the grant to be created"},"requestId":{"type":"string","description":"The unique identifier from the request"},"expiresAt":{"type":"string","format":"date-time","description":"When this link attempt will expire"},"deliveryType":{"$ref":"#/components/schemas/GrantStartResponseDeliveryType","description":"How the verification code was delivered to the consumer"}},"required":["token","requestId","expiresAt","deliveryType"],"title":"GrantStartResponse"},"OnFileGrantStatusUpdatedDataType":{"type":"string","enum":["ON_FILE_GRANT"],"title":"OnFileGrantStatusUpdatedDataType"},"OnFileGrantStatusUpdatedDataObject":{"type":"object","properties":{"grant":{"$ref":"#/components/schemas/Grant"}},"title":"OnFileGrantStatusUpdatedDataObject"},"OnFileGrantStatusUpdatedData":{"type":"object","properties":{"id":{"type":"string"},"type":{"$ref":"#/components/schemas/OnFileGrantStatusUpdatedDataType"},"object":{"$ref":"#/components/schemas/OnFileGrantStatusUpdatedDataObject"}},"required":["id","type","object"],"title":"OnFileGrantStatusUpdatedData"},"OnFileGrantStatusUpdated":{"type":"object","properties":{"type":{"type":"string"},"eventId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/OnFileGrantStatusUpdatedData"}},"required":["type","eventId","createdAt","data"],"title":"OnFileGrantStatusUpdated"}},"securitySchemes":{"sec0":{"type":"http","scheme":"basic"}}}}