Overview

SAP Concur partners with external payment providers for processing invoice payments. These payment providers are listed on the App Center and can integrate with the Invoice product by using the Invoice Pay APIs. Payment providers can get a list of all the payments authorized to be processed by them, and send back status of those payments.

Limitations: This API is only available for use by payment partners who will be processing invoice payments. This API can accept a maximum of 1,000 requests per minute across all payment providers. This API is available only in the North America Data Center.

Process Flow

A process flow diagram of the Invoice Pay API

Products and Editions

  • Concur Invoice Professional Edition
  • Concur Invoice Standard Edition

Scope Usage

Name Description Endpoint
invoice.providerpayment.write Read access to pending payments, and write access to payment status GET,POST

Dependencies

This API can only be used with SAP Concur clients who have purchased Concur Invoice.

Access Token Usage

This API supports only Company access tokens.

Obtaining payments

Payment providers can use this endpoint to get a list of payments.

  • This method will return all payments with a status PENDING_RETRIEVAL and payment method PAVPVD. After an invoice is approved and extracted it will be converted into a payment with status PENDING_RETRIEVAL.
  • It returns a maximum of 500 records at a time. In order to ensure that all payments are retrieved, call this method until you receive an empty payment in the response.
  • The payment provider will need to acknowledge that payments were received, using Updating a Payment With Status and updating the status of the payment to any status other than PENDING_RETRIEVAL.

Request

URI

Template
GET https://us.api.concursolutions.com/invoice/provider-payment/v4/payments

Headers

Payload

None.

Response

Status Codes

Headers

Payload

Payments

Example

Request

GET https://us.api.concursolutions.com/invoice/provider-payment/v4/payments
Accept: application/json
Authorization: BEARER {token}

Response

200 OK
Content-Type: application/json

{
  "payments": [
    {
      "paymentId": "0f27533f-ce38-4f43-a2f3-fa9f0e6b33fc",
      "paymentMethod": "PAYPVD",
      "paymentDueDate": "2018-08-09",
      "totalAmount":{
        "amount": "30.00",
        "currency": "USD"
      },
      "invoices": [
        {
          "invoiceNumber": "AGH87",
          "invoiceID": "1ADFBB440D7045F68DE2",
          "invoiceAmount":{
            "amount": "30.00",
            "currency": "USD"
          },
          "paymentAmount":{
            "amount": "30.00",
            "currency": "USD"
          },
          "notesToSupplier": null
        }
      ],
      "vendor":{
        "addressLine1": "1234 Rain Street",
        "addressLine2": null,
        "addressLine3": null,
        "vendorAddrCode": "1160",
        "city": "Chicago",
        "state": "IL",
        "postalCode": "60680-28160",
        "countryName": "UNITED STATES",
        "countryCode": "US",
        "firstName": "Terry",
        "lastName": "Brown",
        "phoneNumber": null,
        "email": "terry.brown@example.com",
        "vendorCode": "1160",
        "vendorName": "Dell",
        "buyerAccountNumber": "1234567890"
      }
    }
  ]
}

Updating a Payment With Status

Payment providers can use this endpoint to provide updates to the status of payments.

Request

URI

Template
POST https://us.api.concursolutions.com/invoice/provider-payment/v4/payments/{paymentId}

Parameters

Name Type Format Description
paymentId string - Required The identifier of the payment to update.

Headers

Payload

Payment Update

Response

Status Codes

Headers

Payload

Payment Update Result

Example

Request

POST https://us.api.concursolutions.com/invoice/provider-payment/v4/payments/0f27533f-ce38-4f43-a2f3-fa9f0e6b33fc
Authorization: BEARER {token}
Content-Type: application/json

{
  "providerReference" : "hdoesofdl",
  "status" : "PAID",
  "statusMessage" : "Payment was successful",
  "paymentAdjustmentNotes" : null,
  "statusDate" : "2018-05-10",
  "paymentInitiationDate" : "2018-05-09",
  "paymentSettlementDate" : "2018-05-09",
  "thirdPartyPaymentIdentifier" : "69249",
  "paymentMethod" : "CHECK",
  "paidAmount" : {
    "amount": "30.00",
    "currency": "USD"
  }
}

Response

200 OK
Content-Type: application/json

{
  "createdDate" : "2018-05-09",
  "lastModifiedDate" : "2018-05-09",
  "status" : "PAID",
  "statusMessage" : "Payment was successful",
  "paymentAdjustmentNotes" : null,
  "statusDate" : "2018-05-10",
  "paymentInitiationDate" : "2018-05-09",
  "paymentSettlementDate" : "2018-05-09",
  "thirdPartyPaymentIdentifier" : "69249",
  "paymentMethod" : "CHECK",
  "paidAmount" : {
    "amount": "30.00",
    "currency": "USD"
  }
}

Schema

Payments

Name Type Format Description
payments array Payment Array of payments.

Payment

Name Type Format Description
invoices array Invoice Array of invoices that need to be batched in a payment.
paymentDueDate string YYYY-MM-DD The date by which the payment should be made.
paymentID string - Unique identifier of the payment in SAP Concur. Maximum 36 characters.
paymentMethod string - The value is always PAYPVD which means that the client wants to pay using a payment provider. Maximum 15 characters.
totalAmount object Amount This amount needs to be paid to the vendor.
vendor object Vendor Vendor requesting the payment.

Invoice

Name Type Format Description
invoiceAmount object Amount Amount on the invoice.
invoiceNumber string - Invoice Number. Maximum 50 characters.
invoiceId string - Unique identifier of the invoice in SAP Concur. This can be used to get additional invoice information from other APIs. This is the same as paymentRequestID in other Invoice APIs. Maximum 20 characters.
notesToSupplier string - Notes to the supplier contain remittance information that the buyer wants to provide to the supplier. Maximum 500 characters.
paymentAmount object Amount Payment amount on the invoice.

Vendor

Name Type Format Description
buyerAccountNumber string - Buyer Account Number. Maximum 50 characters.
vendorCode string - Vendor Code. Maximum 32 characters.
vendorName string - Vendor Name. Maximum 255 characters.
addressLine1 string - Vendor Address line 1. Maximum 255 characters.
addressLine2 string - Vendor Address line 2. Maximum 255 characters.
addressLine3 string - Vendor Address line 3. Maximum 255 characters.
city string - Vendor Address City. Maximum 255 characters.
state string - Vendor Address State. Maximum 10 characters.
countryCode string - Vendor Address Country Code. Maximum 2 characters.
countryName string - Vendor Address Country Name. Maximum 64 characters.
postalCode string - Vendor Address Postal Code. Maximum 20 characters.
vendorAddrCode string - Vendor Address Code. Maximum 64 characters.
email string - Email Address. Maximum 255 characters.
firstName string - First Name. Maximum 255 characters.
lastName string - Last Name. Maximum 255 characters.
phoneNumber string - Phone Number. Maximum 25 characters.

Amount

Name Type Format Description
amount string - Amount. Maximum 20 characters.
currency string - Currency Code. Maximum 3 characters.

Payment Update

Name Type Format Description
providerReference string - Unique identifier of the payment in the payment provider’s system. This will be used for internal troubleshooting. Maximum 100 characters.
status string Payment Update Status Required Used to depict success, error or any other intermediate state, defined by SAP Concur.
statusMessage string - Payment provider description of the status. Providers can supply any message. Maximum 255 characters.
paymentAdjustmentNotes string - Payment adjustment notes sent by the payment provider. Maximum 255 characters.
statusDate string YYYY-MM-DD Required The date that the payment provider recorded this status change.
paymentInitiationDate string YYYY-MM-DD The date the payment was initiated.
paymentSettlementDate string YYYY-MM-DD The date the payment will be in the payees account.
thirdPartyPaymentIdentifier string - Check number if the payment was done via check or trace number for ACH payments. Maximum 255 characters.
paymentMethod string Payment Provider Method Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Payment method used by the payment provider.
paidAmount object Amount Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Amount paid by the payment provider.

Payment Update Result

Name Type Format Description
createdDate string YYYY-MM-DD The date the payment was created.
lastModifiedDate string YYYY-MM-DD The date the payment was last modified.
providerReference string - Unique identifier of the payment in the payment provider’s system. Maximum 100 characters.
status string Payment Update Status Required Used to depict success, error or any other intermediate state, defined by SAP Concur.
statusMessage string - Payment provider description of the status. Providers can supply any message. Maximum 255 characters.
paymentAdjustmentNotes string - Payment adjustment notes sent by the payment provider. Maximum 255 characters.
statusDate string YYYY-MM-DD Required The date that the payment provider recorded this status change.
paymentInitiationDate string YYYY-MM-DD The date the payment was initiated.
paymentSettlementDate string YYYY-MM-DD The date the payment will be in the payees account.
thirdPartyPaymentIdentifier string - Check number if the payment was done via check or trace number for ACH payments. Maximum 255 characters.
paymentMethod string Payment Provider Method Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Payment method used by the payment provider.
paidAmount object Amount Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Amount paid by the payment provider.

Errors

Name Type Format Description
errors array Error An array of errors.

Error

Name Type Format Description
errorCode string - Required Machine readable code associated with the error.
errorMessage string - Required Human readable message associated with the error.

Definitions

Payment Update Status

Value Description Status available in the Payment Confirmation Extract
PENDING_RETRIEVAL Not yet retrieved by the payment provider Not available
RETRIEVED Retrieved by the payment provider Not available
PROCESSING Payment is being processed by the payment provider Not available
REJECTED Payment was rejected by the payment provider Not available
RETURNED Payment was returned by the bank Not available
CANCELED Payment was canceled FAILED
CHECK_PRINTED Check was printed Not available
CHECK_MAILED Check was mailed Not available
CHECK_PROCESSED Check was processed PAID
CHECK_VOIDED Check was voided VOID
PAID Payment was successfully made PAID
CARD_EMAIL_SENT Email with card information sent to vendor Not available
CARD_AUTHORIZED Card was authorized by the merchant Not available
CARD_SETTLED Card was settled by vendor PAID

Payment Provider Method

Value Description
ACH ACH payment
CHECK Check payment
WIRE Wire payment
CARD Virtual Card payment
OTHER Any other payment method