Skip to content
/
Create purchase

Create purchase

Request

Security
oauth2(Required scopes: draw.purchase:create) or bearerAuth or apiKeyHeader
Path
personIdstring(AnyId)^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+$write-onlyrequired

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

loanIdstring(AnyId)^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+$write-onlyrequired

The unique identifier of the Loan we wish to retrieve. Can be Peach or lender's external identifier.

drawIdstring(AnyId)^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+$write-onlyrequired

The draw identifier.

Query
forceboolean

Allows creating or updating purchases, even if:

  • The purchase amount pushes the line or draw above the credit limit.
  • The line or draw isClosed=true.

If force=true is passed, the forceOverLimit and forceIfClosed parameters are ignored.

Requires the draw.purchase:force permission.

Default:false
forceOverLimitboolean

Allows creating or updating purchases even if the purchase amount pushes the line or draw above the credit limit. Requires the draw.purchase:force permission. If force=true is passed, this parameter is ignored.

Default:false
forceIfClosedboolean

Allows creating or updating purchases even if the line or draw isClosed=true. Requires the draw.purchase:force permission. If force=true is passed, this parameter is ignored.

Default:false
syncboolean

Make the process synchronous.

Default:false
Bodyapplication/json
amountnumber, (float), >= 0required

The amount of the purchase. The amount can be updated only if the purchase status is pending or authorized. The amount and status of a purchase may be changed on the same call.

authorizationPurchaseIdstring or null

Peach's unique (or lender's external identifier) for the authorization purchase. This attribute is used to reference an initial authorization, so lenders know which captures (purchase object(s) in Peach) are related to the original authorization.

cardIdstring or null, <= 200 characters

Peach id, Peach public id (CD-...), or lender external id (ext-...) of the card used for this purchase. Resolved against cards belonging to this line of credit. If the card cannot be resolved (unknown id or wrong loan), the purchase is still created and validation.cardIdMissing is set to true in the response.

In responses from read endpoints, this field is always returned as the Peach public id (CD-...) or null.

declineReasonobject or null(PurchaseDeclineReason)

The reason the purchase was declined

externalIdstring or null, <= 200 characters(externalId)

The external unique identifier of the purchase.

metadataobject or null

Store any type of key/value pairs in the form of a JSON dictionary.

migrationobject or null(PurchaseMigrationDetails)

Purchase migration related details. This object should be used for lines that are migrated from another system to Peach.

originalPurchaseIdstring or null(AnyId)^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+$write-only

Peach's unique or lender's external identifier. Typically used for purchases of type refund which allows the lender to reference the original purchase being refunded. For authorizations, please see authorizationPurchaseId attribute.

purchaseDatestring, (date)

The date of a purchase. This attribute can be passed only during the line of credit migration process. Don't use this attribute after the migration process was successfully completed.

  • The value must be before or equal to today, and cannot be greater than the "migration at date" (aka the actual date on which you run the migration.)
  • If you pass purchaseDate you cannot pass authorizedAt and/or effectiveAt.
  • If purchaseDate is passed, the system will set authorizedAt and effectiveAt to purchaseDate at 6:00 AM in the product timezone.
  • If you purchaseDate is not passed, you must pass both authorizedAt and effectiveAt. authorizedAt cannot be greater than effectiveAt.

For non-migrated purchases:

  • The value is equal to the date part of the authorizedAt converted to the product timezone (e.g. Eastern or Pacific). If authorizedAt is null, this value is equal to the date part of the purchase's createdAt converted to the product timezone.

The purchaseDate is returned in Get endpoints for both migrated and non-migrated purchases.

purchaseDetailsobject(PurchaseDetails)

The details of purchase.

statusstring(PurchaseStatus)

The status of the purchase.

  • authorized - the purchase is authorized and not yet settled. Authorized purchases are included in utilizationAmount, openToBuy and availableCreditAmount calculations; however, authorizations are not written to the ledger and are not included in total outstanding loan balances.
  • settled - the purchase was settled.
  • pending - the purchase is pending. pending purchases increases the draw balance similar to settled. Pending status is used mainly for visuals and normally shown in Borrower Portal and on statements.
  • canceled - the purchase was canceled. canceled purchases reduce the draw balance. A new purchase cannot be created in canceled status.
  • declined - the purchase was declined. declined purchases reduce the draw balance if the status changes from pending to declined. A new purchase can be created in declined status for record purposes (it will not impact the draw balance).
  • disputed - The purchase was disputed for full or partial amount. disputed status is a terminal state and once set cannot be changed to another status. This status can not be set manually. Submitting a purchase dispute will set the purchase's status to disputed.

The following status transitions are allowed:

  • authorized -> pending
  • authorized -> settled
  • authorized -> canceled
  • authorized -> declined
  • pending -> settled
  • pending -> canceled
  • pending -> declined
  • declined -> authorized
  • settled -> canceled
  • settled -> disputed (only by calling "Create purchase dispute")
Default:"settled"
Enum:"authorized""pending""settled""canceled""declined""disputed"
typestring
  • regular - a regular purchase made by the borrower. Increases draw's balance.
  • refund - a refund of the purchase made in the past. Decreases draw's balance.
  • cashBack - cash back given to the borrower by the issuing institution.
Enum:"regular""refund""cashBack"
authorizedAtstring, (date-time)

The timestamp when the purchase was authorized. This value can be set by lenders at the time of purchase creation. If the value is not set by the lender, it will be populated based on authorizedAt (if it is non-null) otherwise createdAt for the corresponding authorizationPurchaseId. If the value is not set by the lender and no authorizationPurchaseId is set, this value corresponds to purchase.authorized event. If the purchase was never in authorized status and none of the prior conditions are met, this value will be null.

effectiveAtstring, (date-time)

The effective timestamp when the purchase was applied in the ledger. This attribute can be passed only during the line of credit migration process. Don't use this attribute after the migration process was successfully completed.

effectiveAt is equal to the timestamp when the purchase is set to pending or settled status, whichever comes first. The timezone is UTC for this timestamp and the format is ISO. For example, in order to set a purchase effectiveAt to July 28th 2022, 10:44 am PDT, send 2022-07-28T17:44:00Z.

POST
/people/{personId}/loans/{loanId}/draws/{drawId}/purchases
curl -i -X POST \
  'https://sandboxapi.peach.finance/api/people/{personId}/loans/{loanId}/draws/{drawId}/purchases?force=false&forceOverLimit=false&forceIfClosed=false&sync=false' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 0,
    "authorizationPurchaseId": "string",
    "cardId": "string",
    "declineReason": {
      "mainExternalReasonCode": "string",
      "mainScriptForRep": "string",
      "mainText": "string"
    },
    "externalId": "string",
    "metadata": {},
    "migration": {
      "originalDrawId": "string"
    },
    "originalPurchaseId": "string",
    "purchaseDate": "2019-08-24",
    "purchaseDetails": {
      "categoryId": "string",
      "conversionRate": 0.1,
      "description": "Purchase",
      "externalCardId": "string",
      "merchantCategoryCode": "string",
      "merchantCity": "string",
      "merchantCountry": "string",
      "merchantId": "string",
      "merchantName": "string",
      "merchantState": "string",
      "metadata": {},
      "originalCurrencyAmount": 0.1,
      "originalCurrencyCode": "string",
      "pointOfSaleType": "online"
    },
    "status": "settled",
    "type": "regular",
    "authorizedAt": "2019-08-24T14:15:22Z",
    "effectiveAt": "2019-08-24T14:15:22Z"
  }'

Responses

Created

Bodyapplication/json
messagestring

Description of the server action or error.

statusinteger

HTTP status code.

dataobject(Purchase)
validationobject(PurchaseValidationWarnings)

Soft validation warnings for fields the system accepted without enforcing.

Response
{
  "message": "string",
  "status": 0,
  "data": {
    "amount": 0,
    "authorizationPurchaseId": "string",
    "cardId": "string",
    "declineReason": { … },
    "displayId": "string",
    "drawId": "string",
    "eligibleDisputeAmount": 0.1,
    "externalId": "string",
    "id": "string",
    "lineOfCreditId": "string",
    "metadata": {},
    "migration": { … },
    "originalAmount": 0.1,
    "purchaseDate": "2019-08-24",
    "purchaseDetails": { … },
    "status": "settled",
    "timestamps": { … },
    "type": "regular",
    "refundDetails": { … }
  },
  "validation": {
    "cardIdMissing": true
  }
}