Oracle Corporation |
Usage Notes for Receivables Standard Receipt REST API |
|
Contents
2.4 Invoking the Standard Receipt REST Service
2.5 Request Processing and Error Handling
3.1 Testing the Standard Receipt Rest Service
3.3 Examples of Sample Payloads
3.3.1 Sample Payload to Create a Standard Receipt
3.3.2 Sample Payload to Get a Receipt
3.3.3 Sample Payload to Find Receipts
3.3.4 Sample Payload to Create a Standard Receipt with Electronic Receipt Method
3.3.5 Sample Payload to Create a Remittance Reference on an Existing Standard Receipt
3.3.6 Sample Payload to Create a Standard Receipt with Remittance References
3.3.7 Sample Payload to Create an Unidentified Customer Receipt
3.3.8 Sample Payload to Add an Attachment to a Receipt
3.3.9 Sample Payload to Add Descriptive Flexfield Information to a Receipt
3.3.10 Sample Payload to Delete a Receipt
Standard receipts are used in Receivables to create Standard, or Cash Receipts to record payments from customers for goods received or services rendered. The Receivables Standard Receipts REST Service integrates the deploying company’s external systems to Oracle Receivables. This service is used to create standard receipts for payments in Oracle Receivables. The user can also use the service to associate one or more remittance references to the standard receipt. Run the Apply Receipts Using Auto-Match process asynchronously to apply the receipts to transactions.
A RESTful API is an Application Programming Interface (API) that uses HTTP standard operations GET, PATCH, POST and DELETE to perform CRUD operations. A RESTful API, also referred as a RESTful web service, is based on representational state transfer (REST) technology, an architectural style and approach to communications often used in web services development. You can test REST services using Oracle’s APEX RESTful service tester; an internet-accessible application; or a programming platform that supports protocols to transfer data, such as POSTMAN, cURL, or other REST clients. An example of how to invoke this service is described in Appendix 2.4. Standard Receipts REST Service is available to any user who has access to Oracle Receivables.
Use the Standard Receipts REST resource to create, find, and delete standard receipts. You can:
· Capture additional information to the standard receipt with descriptive flexfields and global descriptive flexfields.
· Append attachments to the receipt.
The following REST API terminology is commonly used in this document:
Term |
Description |
cURL |
Software that provides a library and command-line tool for transferring data using various protocols. |
<host> |
Fusion cloud URL of the host. |
JSON |
JavaScript Object Notation or JSON is an open-standard file format that uses human-readable text to transmit data objects consisting of attribute value pairs and array data types. |
List of Values (LOV) Resource |
A resource that provides a list of valid values that you can use for a field. |
<passwd> |
Password of the Fusion user. |
<port> |
Port for the host; if port is unknown then leave this field blank. |
Representation |
Used to capture the current or intended state of a resource. It includes both the data that describes the state and the metadata that describes the data. Resources are represented using the JSON format. |
Resource |
An object with a type, associated data, and relationships to other resources. You can use a set of HTTP methods to access each resource. |
Resource Identifier |
Used to identify a resource involved in an interaction, such as URL, URI, or URN. |
Resource Index URI |
The most significant URI for a set of resources. |
REST Service |
An architectural style that defines a set of constraints to be used for creating web services. It provides interoperability between computer systems on the internet. |
Root Resource |
An individual resource that does not require a containing context. It is generally the top-level resource without path parameters and is found in a resource index. |
Singular Resource |
Represents a single entity, such as an invoice. |
StandardReceiptId |
Represents StandardReceiptId generated during receipt creation, if you don’t know this then query the receipt using the GET methods provided above and the response payload will contain StandardReceiptId. |
Subresource |
A resource within the context of a parent resource, such as attachments, notes. |
URL |
Uniform Resource Locator is a reference to a web resource that specifies its location on a computer network and a mechanism for retrieving it. |
URI |
Uniform Resource Identifier is a string of characters that unambiguously identifies a resource such as a file. |
URN |
Uniform Resource Name is a Uniform Resource Identifier that uses the URN scheme. |
Represents the user ID necessary to connect to this service. |
|
<version> |
Version of the service. For example: 11.18.05.0.0 |
The following resources are available from the Standard Receipt REST service:
Attributes and the description of each attribute for each resource are provided in Service Attribute Details Section 2.2. The relationships of the parent and child resources are also available in Section 2.2.
The standard receipts resource is used to create standard receipts in Receivables to record payment from customers for goods received or services rendered. A sample payload for standard receipt service is provided in Appendix 3.3. Further information for this resource is found in the standardReceipts resource service attribute details.
The remittance references resource is used to add one or more remittance references to a standard receipt. The Apply Receipts Using Auto Match process runs asynchronously to apply receipts to transactions. Further information for this resource is found in the remittanceReferences resource service attribute details.
One or more descriptive flexfields can be added to a standard receipt. The standard receipts descriptive flexfields resource is used to add one or more descriptive flexfield values to a standard receipt. Further information for this resource is found in the standardReceiptDFF resource service attribute details.
One or more global descriptive flexfields can be added to a standard receipt. The standard receipts global descriptive flexfields resource is used to add one or more global descriptive flexfield values to a standard receipt. Further information for this resource is found in the standardReceiptGDF resource service attribute details.
One or more attachments can be added to a Standard Receipt. The attachments resource is used to add one or more attachments to a standard receipt. Further information for this resource is found in the attachments resource service attribute details.
This section describes the parent and child relationship of the Standard Receipt REST Service, and the resource attributes:
standardReceipts is the parent resource. The following are children of the standardReceipts resource.
· remittanceReferences
· standardReceiptDFF
· standardReceiptGDF
· attachments
This is the top-level resource that contains information to create a receivables standard receipt.
A sample request payload and response payload for standard receipt is provided in Appendix 3.3.
The attributes of the resource are listed below. You cannot update the standardReceipts attributes.
Attribute Name |
Attribute Type |
Attribute Label |
Attribute Description |
StandardReceiptId |
Number |
Standard Receipt ID |
The unique identifier of the standard receipt. |
ReceiptNumber |
String |
Receipt Number |
The receipt number of the standard receipt. |
BusinessUnit |
String |
Business Unit |
A unit of an enterprise that performs one or more business functions that can be accumulated in a management hierarchy. |
ReceiptMethod |
String |
Receipt Method |
The receipt method used on the standard receipt. |
ReceiptDate |
Date |
Receipt Date |
The date when the standard receipt was created. |
DocumentNumber |
String |
Document Number |
The document sequence number on the standard receipt. |
Amount |
Number |
Receipt Amount |
The amount of a standard receipt. |
Currency |
String |
Currency |
The currency of a standard receipt. |
ConversionRateType |
String |
Conversion Rate Type |
The conversion rate type of a standard receipt. |
ConversionDate |
Date |
Conversion Date |
The date when the standard receipt was converted. |
ConversionRate |
Number |
Conversion Rate |
The conversion rate between the standard receipt currency and the ledger currency. |
State |
String |
State |
The state of the current payment entry progress in the standard receipt. The valid values are APPLIED, UNAPPLIED, UNIDENTIFIED, INSUFFICIENT FUNDS, REVERSE PAYMENT, and STOP PAYMENT. |
Status |
String |
Status |
The status of the entered payment. The valid values are CONFIRMED, CLEARED, APPROVED, and REMITTED. |
RemittanceBankName |
String |
Remittance Bank Name |
The remittance bank name on the standard receipt. |
RemittanceBankBranch |
String |
Remittance Bank Branch |
The remittance bank branch name on the standard receipt. |
RemittanceBankAccountNumber |
String |
Remittance Bank Account Number |
The remittance bank account number on the standard receipt. |
RemittanceBankDepositDate |
Date |
Remittance Bank Deposit Date |
The date when the standard receipt was deposited. |
RemittanceBankAllowOverride |
String |
Remittance Bank Allow Override |
The options that allow the remittance selection process to override the remittance account on a standard receipt. |
CustomerName |
String |
Customer Name |
The name of the customer on the standard receipt. |
TaxpayerIdentificationNumber |
String |
Taxpayer Identification Number |
The tax payer identification number of the customer on the standard receipt. |
CustomerSite |
String |
Customer Site |
The customer site of the customer on the standard receipt. |
CustomerAccountNumber |
String |
Customer Account Number |
The customer account number of the customer on the standard receipt. |
CustomerBank |
String |
Customer Bank |
The bank name of the customer on the standard receipt. |
CustomerBankBranch |
String |
Customer Bank Branch |
The bank branch name of the customer on the standard receipt. |
CustomerBankAccountNumber |
String |
Customer Bank Account Number |
The bank account number of the customer on the standard receipt. |
UnappliedAmount |
Number |
Unapplied Amount |
The receipt amount that is unapplied to any transaction in the receipt currency. |
AccountedAmount |
Number |
Accounted Amount |
The receipt amount in the functional currency. |
AccountingDate |
Date |
Accounting Date |
The date when the standard receipt is accounted. |
MaturityDate |
Date |
Maturity Date |
The date when the standard receipt is matured. |
PostmarkDate |
Date |
Postmark Date |
The date when the standard receipt is postmarked. |
ReceiptAtRisk |
String |
Receipt at Risk |
Identifies whether the receipt is currently at risk with the remittance bank. |
ReceivablesSpecialist |
String |
Receivables Specialist |
The Receivables specialist assigned to the standard receipt. |
Comments |
String |
Comments |
The comments about this receipt. |
CreditCardTokenNumber |
String |
Credit Card Token Number |
The token number issued by tokenization service provider corresponding to a credit card number. |
CreditCardAuthorizationRequestIdentifier |
Number |
Credit Card Authorization Request Identifier |
The authorization request identifier received from the tokenization service provider to authorize the credit card number. |
CardHolderFirstName |
String |
Card Holder First Name |
The first name of the credit card holder. |
CardHolderLastName |
String |
Card Holder Last Name |
The last name of the credit card holder. |
CreditCardIssuerCode |
String |
Credit Card Issuer Code |
The code for the credit card issuer, such as Visa or MasterCard. |
CreditCardExpirationDate |
Date |
Credit Card Expiration Date |
The date when the credit card expires. |
VoiceAuthorizationCode |
String |
Voice Authorization Code |
The voice authorization code received from tokenization service provider for authorization. |
CreatedBy |
String |
Created By |
The user who created the record. |
CreationDate |
DateTime |
Creation Date |
The date when the record was created. |
LastUpdateDate |
DateTime |
Last Update Date |
The date when the record was last updated. |
LastUpdatedBy |
String |
Last Updated By |
The user who last updated the record. |
This child level resource of standardReceipts consists of the attributes of the receipt remittances for the receipt. The receipt remittances attributes describe the information related to the remittance. The attributes of the resource are:
Attribute Name |
Attribute Type |
Attribute Label |
Attribute Description |
RemittanceReferenceId |
Integer |
Remittance Reference ID |
The unique identifier of the remittance reference of the standard receipt. |
ReceiptMatchBy |
String |
Receipt Match By |
The document type used to match the standard receipt to a transaction. |
ReferenceNumber |
String |
Reference Number |
The unique identifier of the selected document type. |
ReferenceAmount |
Integer |
Reference Amount |
The receipt application amount. |
CreatedBy |
String |
Created By |
The user who created the record. |
CreationDate |
DateTime |
Creation Date |
The date when the record was created. |
LastUpdatedBy |
String |
Last Updated By |
The user who last updated the record. |
LastUpdateDate |
DateTime |
Last Update Date |
The date when the record was last updated. |
This child level resource of standardReceipts contains information related to the receipt descriptive flexfields. The attributes of the resource are:
Attribute Name |
Attribute Type |
Attribute Label |
Attribute Description |
CashReceiptId |
Integer |
Cash Receipt ID |
The unique identifier of the receipt associated to the descriptive flexfield. |
__FLEX_Context |
String |
__FLEX_Context Context |
The context of the descriptive flexfield. |
__FLEX_Context_DisplayValue |
String |
N/A |
The display value of the descriptive flexfield context. |
This child level resource of standardReceipts contains information related to the receipt global descriptive flexfields. The attributes of the resource are:
Attribute Name |
Attribute Type |
Attribute Label |
Attribute Description |
CashReceiptId |
Integer |
Cash Receipt ID |
The unique identifier of the receipt associated to the descriptive flexfield. |
__FLEX_Context |
String |
__FLEX_Context Context |
The context of the global descriptive flexfield for receipts. |
__FLEX_Context_DisplayValue |
String |
FLEX_Context Context_Display Value |
The display value of the global descriptive flexfield context. |
This child level resource of standardReceipts contains information related to the attachments to the receipt. The attributes of the resource are:
Attribute Name |
Attribute Type |
Attribute Label |
Attribute Description |
AttachedDocumentId |
N/A |
N/A |
The unique identifier of the attached document. |
LastUpdateDate |
N/A |
N/A |
The date when the record was last updated. |
LastUpdatedBy |
N/A |
N/A |
The user who last updated the record. |
DatatypeCode |
N/A |
N/A |
The value that indicates the data type code of the attachment. |
FileName |
N/A |
N/A |
The file name of the attachment. |
DmFolderPath |
N/A |
N/A |
The folder path of the attachment. |
Url |
N/A |
N/A |
The URL of the attachment. |
CategoryName |
N/A |
N/A |
The category of the attachment. |
UserName |
N/A |
N/A |
The login associated with the attachment. |
Uri |
N/A |
N/A |
The URI of the attachment. |
FileUrl |
N/A |
N/A |
The URL of the attachment. |
UploadedText |
N/A |
N/A |
The text of the attachment. |
UploadedFileContentType |
N/A |
N/A |
The content type of the attachment. |
UploadedFileLength |
N/A |
N/A |
The length of the attachment file. |
UploadedFileName |
N/A |
N/A |
The name of the attachment file. |
ContentRepositoryFileShared |
N/A |
N/A |
Indicates whether the attachment is shared. |
Title |
N/A |
N/A |
The title of the attachment. |
Description |
N/A |
N/A |
The description of the attachment. |
ErrorStatusCode |
N/A |
N/A |
The error code, if any, for the attachment. |
ErrorStatusMessage |
N/A |
N/A |
The error message, if any, for the attachment. |
CreatedBy |
N/A |
N/A |
The user who created the record. |
CreationDate |
N/A |
N/A |
The date when the record was created. |
FileContents |
N/A |
N/A |
The contents of the attachment. |
ExpirationDate |
N/A |
N/A |
The date when the contents in the attachment expire. |
LastUpdatedByUserName |
N/A |
N/A |
The user who last updated the record. |
CreatedByUserName |
N/A |
N/A |
The user who created the record. |
The prerequisite setups needed to invoke the Standard Receipt REST service are the same as that for creating a receipt. These can be set up in the Fusion instance through the Functional Setup Manager.
· Customers
· Receivables System Options
· Receipt Class and Receipt Methods
· Receivables Activity
Flexfields can be set up to record additional information for the invoice. Refer to Standard Receipt Descriptive Flexfields for information on how to leverage flexfields for your business.
To access REST APIs, user roles must have security privileges. You must also include job roles, if any, for the APIs. To use the Standard Receipt REST service, you must have these function security privileges. Add them to custom job roles, as required. You can also include any seeded job role that has the function security privileges mentioned below to access REST services.
Functional Security Privilege Name - AR_CREATE_RECEIVABLES_RECEIPT_PRIV
Resource and Method - standardReceipts (POST)
Functional Security Privilege Name - AR_MANAGE_RECEIVABLES_RECEIPT_PRIV
Resource and Method - standardReceipts (GET and DELETE)
URL Path for the Standard Receipt REST Services
The URL paths for all the ERP REST resources use the new root context value fscmRestApi.
Example REST API URL path for Standard Receipt Service is
https://<host>:<port>//fscmRestApi/resources/11.13.x.x/standardReceipts
11.13.x.x has to be replaced with the current version of REST API delivered and the same would be documented in Oracle Help Center REST API documentation.
Release 13 URL Path
https://<host>:<port>//fscmRestApi/resources/11.13.0.0/standardReceipts
When a service request is processed, a number of scenarios could occur. The request could return a response, it could error with a handled exception, or error with an unhandled exception.
Please refer to Appendix 3.4 for the details of the error messages and the corresponding message text associated with each error message.
Here are some examples of situations which could be encountered when a request is submitted:
a) A service request is submitted and successfully processed:
For example: if a create standard receipt request is submitted and successfully processed, a response is returned. The response would create a receipt.
b) In the case of a handled exception, if a service request is submitted and the response did not come up with any matching information, it will return a message.
For example: a service request to create a receipt is submitted and a response is returned. However, the system could not create the receipt because there is no matching customer name. The response would communicate an error message to the user ‘The customer name is invalid.’
c) In the case of an unhandled exception, if a service request is submitted, and there is no response from the REST service, it will return with a status:
For example: a service request to get a receipt is submitted, but the server is down, and the request could not be processed. When an unexpected condition is encountered, and no specific message is suitable, the system would return a status code of ‘500 Internal Server Error’.
You can test REST services using Oracle’s APEX RESTful service test, an internet-accessible application, or a programming platform that supports protocols to transfer data, such as POSTMAN, cURL, or other REST clients.
The following table shows examples of the POST, GET, and DELETE operations on the standardReceipts resource using cURL.
Operation |
cURL Command |
POST (Creating a Standard Receipt) |
curl --user <username>:<password> -X POST -H "Content-Type: application/vnd.oracle.adf.resourceitem+json" --data @create_standard_receipt_payload.json https://<host>:<port>/fscmRestApi/resources/<version>/standardReceipts
Ensure to create json file given as input in request with a valid payload. Refer to below example of payloads in this section to understand various attributes of this service. |
POST (Create one or more Remittance References) |
curl --user <username>:<password> -X POST -H "Content-Type: application/vnd.oracle.adf.resourceitem+json" --data @create_remittance_reference_payload.json https://<host>:<port>/fscmRestApi/resources/<version>/standardReceipts/<StandardReceiptId>/child/remittanceReferences
|
POST (Create one or more Standard Receipt DFFs) |
curl --user <username>:<password> -X POST -H "Content-Type: application/vnd.oracle.adf.resourceitem+json" --data @create_dff_payload.json https://<host>:<port>/fscmRestApi/resources/<version>/standardReceipts/<StandardReceiptId>/child/standardReceiptDFF |
POST (Create one or more Standard Receipt GDFs) |
curl --user <username>:<password> -X POST -H "Content-Type: application/vnd.oracle.adf.resourceitem+json" --data @create_gdf_payload.json https://<host>:<port>/fscmRestApi/resources/<version>/standardReceipts/<StandardReceiptId>/child/standardReceiptGdf |
POST (Create one or more Standard Receipt Attachments) |
curl --user <username>:<password> -X POST -H "Content-Type: application/vnd.oracle.adf.resourceitem+json" --data @create_attachments_payload.json https://<host>:<port>/fscmRestApi/resources/<version>/standardReceipts/<StandardReceiptId>/child/attachments |
GET (Retrieving a Standard Receipt using implicit Primary Key finder) |
curl --user <Username>:<password> -X GET https://<host>:<port>//fscmRestApi/resources/<version>/standardReceipts?finder=PrimaryKey;StandardReceiptId=<StandardReceiptId> |
GET (Retrieve a Standard Receipt using explicit finder) |
curl --user <Username>:<password> -X GET https://<host>:<port>//fscmRestApi/resources/<version>/standardReceipts?finder=StandardReceiptsFinder;ReceiptNumber=<ReceiptNumber>
Note: Check finder section in notes to see all available attributes which can be used to query a receipt. |
GET (Retrieve all Remittance References) |
curl --user <Username>:<password> -X GET https://<host>:<port>//fscmRestApi/resources/<version>/standardReceipts/<StandardReceiptId>/child/remittanceReferences |
GET (Retrieve all Standard Receipt DFFs) |
curl --user <Username>:<password> -X GET https://<host>:<port>//fscmRestApi/resources/<version>/standardReceipts/<StandardReceiptId>/child/standardReceiptDFF |
GET (Retrieve all Standard Receipt GDFs) |
curl --user <Username>:<password> -X GET https://<host>:<port>//fscmRestApi/resources/<version>/standardReceipts/<StandardReceiptId>/child/standardReceiptGdf |
GET (Retrieve all Standard Receipt Attachments) |
curl --user <Username>:<password> -X GET https://<host>:<port>//fscmRestApi/resources/<version>/standardReceipts/<StandardReceiptId>/child/attachments |
DELETE (Deleting a Standard Receipt) |
curl --user <username>:<passwd> -X DELETE https://<host>:<port>/fscmRestApi/resources/<version>/standardReceipts/<StandardReceiptId>
|
The typical use cases for the Standard Receipt REST Service are shown below:
a) Use Case: Create a standard receipt
You can use the standard receipts resource to create standard receipts in Receivables to record payment from customers for goods received or services rendered.
Example:
A customer payment is made to an external customer payment reference system. The external feeder system then makes a REST call to record the customer payment in Oracle Receivables.
REST Service
Use the API to import data from an external payment reference system, for example a web store, a self-service customer account portal, or any spreadsheet-based tool for payment upload, to create receipts and record the customer payments in Oracle Receivables.
Refer to Appendix 3.3.1 for the sample request and response payload to create a standard receipt.
b) Use Case: Get a receipt
You can use the Get Method of the Standard Receipt Service to retrieve details of a specific payment to know its details or to trigger follow-up action.
Example:
A customer logs in to a self-service customer portal to find and retrieve the customer payment to view details of the receipt including the status of the payment and its history.
REST Service
Use the self-service portal to make a REST service call to get the customer payment that satisfies the search criteria.
Refer to Appendix 3.3.2 for the sample request and response payload to get a receipt.
c) Use Case: Find receipts
You can retrieve one or more payments made for a specific customer account, the payment date and other search criteria. The search parameters include Receipt Number, Receipt Date, Customer Name, Customer Account Number, and Customer Site.
Example:
A customer logs in to a self-service customer portal to find and retrieve one or more payments to view details of the receipt including the current status of the payment and its history.
REST Service
Use the self-service portal to retrieve one or more receipts that satisfy the search criteria.
Refer to Appendix 3.3.3 for the sample request and response payload to find receipts.
d) Use Case: Create a standard receipt with electronic receipt method
You can use the standard receipts resource to create standard receipts in Receivables to record payment from customers for goods received or services rendered. The payment can be made using an electronic receipt method like a credit card or bank account transfer.
Example:
A user logs into a web store and adds a certain item to the cart. He then makes a payment for a one-time shopping cart sale transaction using electronic payment.
REST Service
Use the REST service to record the customer payment by providing the credit card token details. If the credit card payment has been authorized already, then the authorization request identifier may also be provided for validation.
· For a customer payment made using bank account transfer, the customer bank account number is required.
· Use the API to import data from an external payment reference system, for example a web store or a self-service customer account portal to create receipts paid using a credit card or bank account transfer.
Refer to Appendix 3.3.4 for the sample request and response payload to create a standard receipt with electronic receipt method.
e) Use Case: Create a remittance reference on an existing standard receipt
You can use the remittance references resource to add a remittance reference to an existing Standard Receipt. One or more remittance references can also be created during Standard Receipt creation.
Example:
A customer logs in in to a self-service portal to retrieve details of a payment made and recorded as an unapplied receipt. The customer then proceeds to provide the invoice references to which the payment can be applied.
REST Service
Use the self-service portal to make a REST service call using the remittance References resource and add the remittance references to the standard receipt. Run the Apply Receipts Using AutoMatch process to apply the receipt asynchronously.
Refer to Appendix 3.3.5 for the sample request and response payload to create a remittance reference on an existing standard receipt.
f) Use Case: Create a standard receipt with remittance references
You can use the standard receipts resource to create standard receipts in Receivables to record payment from customers for goods received or services rendered. One or more remittance references can also be provided when applying the receipt to transactions using the Apply Receipts Using AutoMatch process. The remittance References child resource is used to add the remittance references to the standard receipt.
Example:
A customer places an online order that is billed and paid through a web store. The web store then makes a REST call to record the customer payment along with details of the sales invoices for which the payment is being made and any existing credits to be applied to the customer payment.
REST Service
Use the API to import data to create receipts and provide the transaction references for which the payment is being made for. Use the remittance references resource to add the remittance references to the standard receipt. Run the Apply Receipts Using AutoMatch process to apply the receipt asynchronously.
Refer to Appendix 3.3.6 for the sample request and response payload to create a standard receipt with remittance references.
g) Use Case: Create an unidentified customer receipt
You can use the standard receipts resource to create standard receipts in Receivables to record payment where the customer is unidentified.
Example:
A user receives payment from an external payment reference system like a spreadsheet-based tool for payment upload. However, the customer information is not included in the payment.
REST Service
A payment is recorded from an external customer payment reference system; however, the customer making the payment is unknown. The external feeder system makes a REST call to record the payment in Oracle Receivables as an unidentified receipt.
Refer to Appendix 3.3.7 for the sample request and response payload to create an unidentified customer receipt.
h) Use Case: Add an attachment to a receipt
You can use the standard receipts resource to create standard receipts in Receivables to record payment and add attachments to support the payment.
Example:
A customer’s information regarding remittance for a receipt to apply to an invoice is sent to the seller. A remittance advice image is added as an attachment to the receipt.
REST Service
Use the feeder application API to make a REST call to record the payment in Oracle Receivables along with the attachment to the receipt.
Refer to Appendix 3.3.8 for the sample request and response payload to add an attachment to a receipt.
i) Use Case: Add a descriptive flexfield information to a receipt
You can use the standard receipts resource to create standard receipts in Receivables to record payment along with additional information to support the payment.
Example:
The user receives information regarding a customer payment that the payment is for a related subsidiary. The information is added to the receipt flexfield.
REST Service
Use the API to import data from an external payment processing system to create receipts along with populating the additional information relevant to the receipt. This helps the reconciliation of the data between both the systems.
Refer to Appendix 3.3.9 for the sample request and response payload to add a descriptive flexfield to a receipt.
You can use the standard receipts resource to delete standard receipts in Receivables. For example, a receipt was created with incorrect information and, the receipt needs to be deleted as per the business process. The delete method of the REST resource will be used to perform the operation.
Example:
A receipt is created in Oracle Receivables using a spreadsheet-based payment upload tool . A user realizes that the receipt has been created with the wrong receipt method and wishes to delete the receipt.
REST Service
Use the API to make a REST Service call to delete the receipt created in Oracle Receivables to keep both the external system and Oracle Receivables in sync.
Refer to Appendix 3.3.10 for the sample request and response payload to delete a receipt.
Following section provides the sample Request and Response payloads for the operations in Standard Receipt REST service.
Sample URL
https://<host>:<port>/fscmRestApi/resources/<version>/standardReceipts
HTTP Operation: POST
Sample Request Payload that the Client Sends
{
"ReceiptNumber":"SKR_Receipt_1008",
"ReceiptMethod":"Manual",
"BusinessUnit":"Vision Operations",
"Amount":451.23,
"Currency":"USD",
"RemittanceBankAccountNumber":"10271-17621-619"
}
Sample Response Payload that the Client Receives
{
"StandardReceiptId": 300100153164586,
"ReceiptNumber": "SKR_Receipt_1008",
"BusinessUnit": "Vision Operations",
"ReceiptMethod": "Manual",
"ReceiptDate": "2018-08-17",
"DocumentNumber": null,
"Amount": 451.23,
"Currency": "USD",
"ConversionRateType": null,
"ConversionDate": null,
"ConversionRate": null,
"State": null,
"Status": null,
"RemittanceBankName": null,
"RemittanceBankBranch": null,
"RemittanceBankAccountNumber": "10271-17621-619",
"RemittanceBankDepositDate": "2018-08-17",
"RemittanceBankAllowOverride": "N",
"CustomerName": null,
"TaxpayerIdentificationNumber": null,
"CustomerSite": null,
"CustomerAccountNumber": null,
"CustomerBank": null,
"CustomerBankBranch": null,
"CustomerBankAccountNumber": null,
"UnappliedAmount": null,
"AccountedAmount": null,
"AccountingDate": "2018-08-17",
"MaturityDate": "2018-08-17",
"PostmarkDate": null,
"ReceiptAtRisk": null,
"ReceivablesSpecialist": null,
"Comments": null,
"CreditCardTokenNumber": null,
"CreditCardAuthorizationRequestIdentifier": null,
"CardHolderFirstName": null,
"CardHolderLastName": null,
"CreditCardIssuerCode": null,
"CreditCardExpirationDate": null,
"VoiceAuthorizationCode": null,
"CreatedBy": "AR_MGR_OPERATIONS",
"CreationDate": "2018-08-17T03:41:51.002+00:00",
"LastUpdateDate": "2018-08-17T03:41:52.719+00:00",
"LastUpdatedBy": "AR_MGR_OPERATIONS",
"links": […..]
}
Sample URL
https://<host>:<port>/fscmRestApi/resources/<version>/standardReceipts?finder=Primary;StandardReceiptId=<StandardReceiptId>
OR
https://<host>:<port>/fscmRestApi/resources/<version>/standardReceipts?q=StandardReceiptId=<StandardReceiptId>
HTTP Operation: GET
Sample Request Payload that the Client Sends
No request payload is required for GET operation
Sample Response Payload that the Client Receives
{
"items": [
{
"StandardReceiptId": 300100153152555,
"ReceiptNumber": "Rec5_160818235710",
"BusinessUnit": "Vision Operations",
"ReceiptMethod": "AR_ManRec_02",
"ReceiptDate": "2018-08-15",
"DocumentNumber": null,
"Amount": 505.58,
"Currency": "USD",
"ConversionRateType": null,
"ConversionDate": null,
"ConversionRate": null,
"State": "Unapplied",
"Status": "Confirmed",
"RemittanceBankName": "Bank of America",
"RemittanceBankBranch": "New York",
"RemittanceBankAccountNumber": "10271-17621-619",
"RemittanceBankDepositDate": "2018-08-16",
"RemittanceBankAllowOverride": "Y",
"CustomerName": "B2CM_Customer01",
"TaxpayerIdentificationNumber": null,
"CustomerSite": null,
"CustomerAccountNumber": "CDRM_3195",
"CustomerBank": null,
"CustomerBankBranch": null,
"CustomerBankAccountNumber": null,
"UnappliedAmount": 505.58,
"AccountedAmount": 505.58,
"AccountingDate": "2018-08-15",
"MaturityDate": "2018-08-16",
"PostmarkDate": null,
"ReceiptAtRisk": "Y",
"ReceivablesSpecialist": null,
"Comments": null,
"CreditCardTokenNumber": null,
"CreditCardAuthorizationRequestIdentifier": null,
"CardHolderFirstName": null,
"CardHolderLastName": null,
"CreditCardIssuerCode": null,
"CreditCardExpirationDate": null,
"VoiceAuthorizationCode": null,
"CreatedBy": "AR_MGR_OPERATIONS",
"CreationDate": "2018-08-16T18:29:51.084+00:00",
"LastUpdateDate": "2018-08-16T18:31:35+00:00",
"LastUpdatedBy": "AR_MGR_OPERATIONS",
"links": […]
}
Sample URL
https://<host>:<port>//fscmRestApi/resources/<version>/standardReceipts?finder=StandardReceiptsFinder;ReceiptNumber=Rec5_160818235710
HTTP Operations: GET
Sample Request Payload that the Client Sends
No request payload is required for GET operation
Sample Response Payload that the Client Receives
{
"items": [
{
"StandardReceiptId": 300100153152555,
"ReceiptNumber": "Rec5_160818235710",
"BusinessUnit": "Vision Operations",
"ReceiptMethod": "AR_ManRec_02",
"ReceiptDate": "2018-08-15",
"DocumentNumber": null,
"Amount": 505.58,
"Currency": "USD",
"ConversionRateType": null,
"ConversionDate": null,
"ConversionRate": null,
"State": "Unapplied",
"Status": "Confirmed",
"RemittanceBankName": "Bank of America",
"RemittanceBankBranch": "New York",
"RemittanceBankAccountNumber": "10271-17621-619",
"RemittanceBankDepositDate": "2018-08-16",
"RemittanceBankAllowOverride": "Y",
"CustomerName": "B2CM_Customer01",
"TaxpayerIdentificationNumber": null,
"CustomerSite": null,
"CustomerAccountNumber": "CDRM_3195",
"CustomerBank": null,
"CustomerBankBranch": null,
"CustomerBankAccountNumber": null,
"UnappliedAmount": 505.58,
"AccountedAmount": 505.58,
"AccountingDate": "2018-08-15",
"MaturityDate": "2018-08-16",
"PostmarkDate": null,
"ReceiptAtRisk": "Y",
"ReceivablesSpecialist": null,
"Comments": null,
"CreditCardTokenNumber": null,
"CreditCardAuthorizationRequestIdentifier": null,
"CardHolderFirstName": null,
"CardHolderLastName": null,
"CreditCardIssuerCode": null,
"CreditCardExpirationDate": null,
"VoiceAuthorizationCode": null,
"CreatedBy": "AR_MGR_OPERATIONS",
"CreationDate": "2018-08-16T18:29:51.084+00:00",
"LastUpdateDate": "2018-08-16T18:31:35+00:00",
"LastUpdatedBy": "AR_MGR_OPERATIONS",
"links": […]
}
Sample URL
https://<host>:<port>/fscmRestApi/resources/<version>/standardReceipts
HTTP Operation: POST
Sample Request Payload that the Client Sends
{
"ReceiptNumber":"SKR_Receipt_1009",
"ReceiptMethod":"AR_AutoRec_RRF2",
"BusinessUnit":"Vision Operations",
"Amount":451.23,
"Currency":"USD",
"RemittanceBankAccountNumber":"10271-17621-619",
"CustomerAccountNumber":"1004",
"CustomerSite":"Tulsa (OPS)",
"CreditCardTokenNumber":"9876543567892342",
"CardHolderFirstName":"Sanjay",
"CardHolderLastName":"Kumar",
"CreditCardExpirationDate":"2022-05-31",
"CreditCardIssuerCode":"VISA"
}
Sample Response Payload that the Client Receives
{
"StandardReceiptId": 300100153164601,
"ReceiptNumber": "SKR_Receipt_1009",
"BusinessUnit": "Vision Operations",
"ReceiptMethod": "AR_AutoRec_RRF2",
"ReceiptDate": "2018-08-17",
"DocumentNumber": null,
"Amount": 451.23,
"Currency": "USD",
"ConversionRateType": null,
"ConversionDate": null,
"ConversionRate": null,
"State": null,
"Status": null,
"RemittanceBankName": null,
"RemittanceBankBranch": null,
"RemittanceBankAccountNumber": "10271-17621-619",
"RemittanceBankDepositDate": "2018-08-17",
"RemittanceBankAllowOverride": "N",
"CustomerName": null,
"TaxpayerIdentificationNumber": null,
"CustomerSite": "Tulsa (OPS)",
"CustomerAccountNumber": "1004",
"CustomerBank": null,
"CustomerBankBranch": null,
"CustomerBankAccountNumber": null,
"UnappliedAmount": null,
"AccountedAmount": null,
"AccountingDate": "2018-08-17",
"MaturityDate": "2018-08-17",
"PostmarkDate": null,
"ReceiptAtRisk": null,
"ReceivablesSpecialist": null,
"Comments": null,
"CreditCardTokenNumber": "9876543567892342",
"CreditCardAuthorizationRequestIdentifier": null,
"CardHolderFirstName": "Sanjay",
"CardHolderLastName": "Kumar",
"CreditCardIssuerCode": "VISA",
"CreditCardExpirationDate": "2022-05-31",
"VoiceAuthorizationCode": null,
"CreatedBy": "AR_MGR_OPERATIONS",
"CreationDate": "2018-08-17T03:53:17.001+00:00",
"LastUpdateDate": "2018-08-17T03:53:19.610+00:00",
"LastUpdatedBy": "AR_MGR_OPERATIONS"
}
Sample URL
https://<host>:<port>/fscmRestApi/resources/<version>/standardReceipts/<StandardReceiptId>/child/remittanceReferences
HTTP Operation: POST
Sample Request Payload that the Client Sends
{
"ReceiptMatchBy":"Purchase Order",
"ReferenceNumber":"SK_PO_1012",
"ReferenceAmount":"8774.45"
}
Sample Response Payload that the Client Receives
{
"RemittanceReferenceId": 300100153164605,
"ReceiptMatchBy": "Purchase Order",
"ReferenceNumber": "SK_PO_1012",
"ReferenceAmount": 8774.45,
"CreatedBy": "AR_MGR_OPERATIONS",
"CreationDate": "2018-08-17T03:55:50+00:00",
"LastUpdatedBy": "AR_MGR_OPERATIONS",
"LastUpdateDate": "2018-08-17T03:55:50.095+00:00",
"links": […]
}
Sample URL
https://<host>:<port>/fscmRestApi/resources/<version>/standardReceipts
HTTP Operation: POST
Sample Request Payload that the Client Sends
{
"ReceiptNumber":"SKR_Receipt_1011",
"ReceiptMethod":"Manual",
"BusinessUnit":"Vision Operations",
"Amount":8774.45,
"Currency":"USD",
"RemittanceBankAccountNumber":"10271-17621-619",
"remittanceReferences":
[ {
"ReceiptMatchBy":"Purchase Order",
"ReferenceNumber":"SK_PO_1012",
"ReferenceAmount":"8774.45"
},
{
"ReceiptMatchBy":"Transaction Number",
"ReferenceNumber":"SK_INV_1011",
"ReferenceAmount":"8774.45"
}
]
}
Sample Response Payload that the Client Receives
Response received is similar to any other response of Create Receipt.
{
"StandardReceiptId" : 300100153164611,
"ReceiptNumber" : "SKR_Receipt_1011",
"BusinessUnit" : "Vision Operations",
"ReceiptMethod" : "Manual",
"ReceiptDate" : "2018-08-17",
"DocumentNumber" : null,
"Amount" : 8774.45,
"Currency" : "USD",
"ConversionRateType" : null,
"ConversionDate" : null,
"ConversionRate" : null,
"State" : null,
"Status" : null,
"RemittanceBankName" : null,
"RemittanceBankBranch" : null,
"RemittanceBankAccountNumber" : "10271-17621-619",
"RemittanceBankDepositDate" : "2018-08-17",
"RemittanceBankAllowOverride" : "N",
"CustomerName" : null,
"TaxpayerIdentificationNumber" : null,
"CustomerSite" : null,
"CustomerAccountNumber" : null,
"CustomerBank" : null,
"CustomerBankBranch" : null,
"CustomerBankAccountNumber" : null,
"UnappliedAmount" : null,
"AccountedAmount" : null,
"AccountingDate" : "2018-08-17",
"MaturityDate" : "2018-08-17",
"PostmarkDate" : null,
"ReceiptAtRisk" : null,
"ReceivablesSpecialist" : null,
"Comments" : null,
"CreditCardTokenNumber" : null,
"CreditCardAuthorizationRequestIdentifier" : null,
"CardHolderFirstName" : null,
"CardHolderLastName" : null,
"CreditCardIssuerCode" : null,
"CreditCardExpirationDate" : null,
"VoiceAuthorizationCode" : null,
"CreatedBy" : "AR_MGR_OPERATIONS",
"CreationDate" : "2018-08-17T03:58:52.001+00:00",
"LastUpdateDate" : "2018-08-17T03:58:52.247+00:00",
"LastUpdatedBy" : "AR_MGR_OPERATIONS",
"remittanceReferences" : [ {
"RemittanceReferenceId" : 300100153164612,
"ReceiptMatchBy" : "Purchase Order",
"ReferenceNumber" : "SK_PO_1012",
"ReferenceAmount" : 8774.45,
"CreatedBy" : "AR_MGR_OPERATIONS",
"CreationDate" : "2018-08-17T03:58:52.199+00:00",
"LastUpdatedBy" : "AR_MGR_OPERATIONS",
"LastUpdateDate" : "2018-08-17T03:58:52.250+00:00"
},
{
"RemittanceReferenceId" : 300100153164613,
"ReceiptMatchBy" : "Transaction Number",
"ReferenceNumber" : "SK_INV_1011",
"ReferenceAmount" : 8774.45,
"CreatedBy" : "AR_MGR_OPERATIONS",
"CreationDate" : "2018-08-17T03:58:52.212+00:00",
"LastUpdatedBy" : "AR_MGR_OPERATIONS",
"LastUpdateDate" : "2018-08-17T03:58:52.252+00:00"
}
]
}
Sample URL
https://<host>:<port>/fscmRestApi/resources/<version>/standardReceipts
HTTP Operations: POST
Sample Request Payload that the Client Sends
{
"ReceiptNumber":"SKR_Receipt_1012",
"ReceiptMethod":"Manual",
"BusinessUnit":"Vision Operations",
"Amount":451.23,
"Currency":"USD",
"RemittanceBankAccountNumber":"10271-17621-619"
}
Sample Response Payload that the Client Receives
{
"StandardReceiptId" : 300100153164619,
"ReceiptNumber" : "SKR_Receipt_1012",
"BusinessUnit" : "Vision Operations",
"ReceiptMethod" : "Manual",
"ReceiptDate" : "2018-08-17",
"DocumentNumber" : null,
"Amount" : 451.23,
"Currency" : "USD",
"ConversionRateType" : null,
"ConversionDate" : null,
"ConversionRate" : null,
"State" : null,
"Status" : null,
"RemittanceBankName" : null,
"RemittanceBankBranch" : null,
"RemittanceBankAccountNumber" : "10271-17621-619",
"RemittanceBankDepositDate" : "2018-08-17",
"RemittanceBankAllowOverride" : "N",
"CustomerName" : null,
"TaxpayerIdentificationNumber" : null,
"CustomerSite" : null,
"CustomerAccountNumber" : null,
"CustomerBank" : null,
"CustomerBankBranch" : null,
"CustomerBankAccountNumber" : null,
"UnappliedAmount" : null,
"AccountedAmount" : null,
"AccountingDate" : "2018-08-17",
"MaturityDate" : "2018-08-17",
"PostmarkDate" : null,
"ReceiptAtRisk" : null,
"ReceivablesSpecialist" : null,
"Comments" : null,
"CreditCardTokenNumber" : null,
"CreditCardAuthorizationRequestIdentifier" : null,
"CardHolderFirstName" : null,
"CardHolderLastName" : null,
"CreditCardIssuerCode" : null,
"CreditCardExpirationDate" : null,
"VoiceAuthorizationCode" : null,
"CreatedBy" : "AR_MGR_OPERATIONS",
"CreationDate" : "2018-08-17T04:08:39.001+00:00",
"LastUpdateDate" : "2018-08-17T04:08:39.194+00:00",
"LastUpdatedBy" : "AR_MGR_OPERATIONS",
"links" : [ {…}]
}
Sample URL
https://<host>:<port>/fscmRestApi/resources/<version>/standardReceipts
Sample Request Payload that the Client Sends
< Payload with mandatory parameters only >
Sample Response Payload that the Client Receives
< Basic create payload response >
Sample URL
https://<host>:<port>/fscmRestApi/resources/<version>/standardReceipts
HTTP Operation: POST
Sample Request Payload that the Client Sends
{
"ReceiptNumber":"SKR_Receipt_1011",
"ReceiptMethod":"Manual",
"BusinessUnit":"Vision Operations",
"Amount":451.23,
"Currency":"USD",
"RemittanceBankAccountNumber":"10271-17621-619",
"standardReceiptDFF":
[ {
"__FLEX_Context":"Third Party",
"firstName":"Sanjay",
"lastName":"Kumar"
}
]
}
Sample Response Payload that the Client Receives
{
“items”: [
{
“StandardReceiptId”: 30010015809725,
“ReceiptNumber”: “SKR_DFF_TEST_1007”,
“BusinessUnit”: “Vision Operations”,
“ReceiptMethod”: “Manual”,
“ReceiptDate”: “2018-07-16”,
“DocumentNumber”: null,
“Amount”: 451.23,
“Currency”: “USD”,
“ConversionRateType”: null,
“ConversionDate”: null,
“ConversionRate”: null,
“State”: “Unapplied”,
“Status”: “Cleared”,
“RemittanceBankName”: “Bank of America”,
“RemittanceBankBranch”: “New York”,
“RemittanceBankAccountNumber”: “10271-17621-619”,
“RemittanceBankDepositDate”: “2018-07-16”,
“RemittanceBankAllowOverride”: “N”,
“CustomerName”: “Hillman and Associates”,
“TaxpayerIdentificationNumber”: “78-45664786”,
“CustomerSite”: “Tulsa (OPS)”,
“CustomerAccountNumber”: “1004”,
“CustomerBank”: null,
“CustomerBankBranch”: null,
“CustomerBankAccountNumber”: null,
“UnappliedAmount”: 451.23,
“AccountedAmount”: 451.23,
“AccountingDate”: “2018-07-16”
“MaturityDate”: “2018-07-16”
“PostmarkDate”: null,
“ReceiptAtRisk”: “N”,
“ReceivablesSpecialist”: null,
“Comments”: null,
“CreditCardTokenNumber”: null,
“CreditCardAuthorizationRequestIdentifier”: null,
“CardHolderFirstName”: null,
“CardHolderLastName”: null,
“CreditCardIssuerCode”: null,
“CreditCardExpirationDate”: null,
“VoiceAuthorizationCode”: null,
“CreatedBy”: “AR_MGR_OPERATIONS”,
“CreationDate”: “2018-07-16T13:59:51.001+00:00”,
“LastUpdateDate”: “2018-07-16T13:59:51.331+00:00”,
“LastUpdatedBy”: “AR_MGR_OPERATIONS”,
}
Sample URL
https://<host>:<port>/fscmRestApi/resources/<version>/standardReceipts/300100151809664
HTTP Operation: DELETE
Sample Request Payload that the Client Sends
No payload is required in order to delete a Standard Receipt.
Sample Response Payload that the Client Receives
Server sends 204 response code if deletion of a Standard Receipt was successful and response body contains no data.
Note: You can-not delete a receipt with the receipt number only. The StandardReceiptId which is the unique identifier for a receipt needs to be provided in the URL in order to delete a receipt.
When the service request is being processed and an error is encountered, the nature of the error will be communicated to the client. The table below shows the error message numbers, message names, and accompanying text that describes each error.
Standard Receipt REST Service Error Messages Table
Message Name |
Message Text |
AR_RCP_DUP_NUM |
A receipt with this number, date, amount and customer already exists. Enter a unique receipt number. |
FND_CMN_REQ_ATTRIB_API_SERV |
You must provide a value for the attribute {ATTRIBUTE_NAME}. |
AR_RAPI_BU_INVALID |
The business unit is invalid. |
AR_INVAL_RECEIPT_MTH_ID |
The receipt method that you selected is invalid. |
AR_BOE_OBSOLETE |
Bills of exchange receipt methods are no longer valid. Enter another receipt method. |
AR_RAPI_CURR_CODE_INVALID |
The currency is invalid. |
AR_RW_RCT_AMOUNT_NEGATIVE |
You cannot enter a negative receipt amount for cash receipts. |
AR_INVALID_ACCOUNTING_DATE |
The accounting date {GL_DATE} is not in an open or future-enterable period. |
AR_RAPI_CUS_NAME_INVALID |
The customer name is invalid. |
AR_RCP_INVALID_CUSTACCTNUM |
Enter a valid customer account number for the receipt. |
AR_RAPI_CUS_LOC_INVALID |
Enter a valid site for the customer. |
AR_RAPI_REM_BK_AC_NUM_INVALID |
The remittance bank account number is invalid. |
AR_INVAL_EXCHG_RATE_TYPE |
You entered an invalid conversion rate type on the transaction. |
AR_EXCHANGE_RATE |
There is no valid conversion rate for the conversion rate type {P_EXCHANGE_RATE_TYPE} and currency {CURRENCY} as of {P_AS_OF_DATE}. |
AR_EXCHANGE_RATE_NEGATIVE |
Enter a positive conversion rate. |
AR_EXCHANGE_RATE_NEEDED |
Enter conversion rate information. |
AR_RAPI_CUS_BK_AC_NUM_INVALID |
The customer bank account number is invalid. |
AR_RCP_INVALID_MATCHBY |
Enter a valid Receipt Match By for the remittance reference for the receipt. |
IBY_CARDBRAND_NOT_ACCEPTED |
The card brand you entered is not accepted. |
FND_CMN_REQ_ATTRIB_API_SERV |
You must provide a value for the attribute {ATTRIBUTE_NAME}. |
AR_BU_NOT_FOUND |
The business unit you entered does not exist. |
AR_RAXTRX-1763 |
The receipt method is Automatic. Either provide a valid bank account or define a bill-to customer primary bank account for the currency of the transaction. |
AR_REC_DELETE_REF_IN_MISC |
You cannot delete the receipt because it is referenced by a miscellaneous receipt. |
AR_RCP_DEL_REC_POSTED |
You can't delete posted receipts. |
AR_RCP_DEL_REV_RECEIPT |
You can't delete reversed receipts. |
AR_RCP_DEL_REC_WITH_APPS |
You can't delete receipts with applications. |
AR_RCPT_STATUS_CHG_DELETE |
You cannot delete the receipt because the receipt status changed since your last query. |
AR_RCP_PAY_DEL_FLAG |
You can't delete the receipt. Payment deletion isn't enabled for this business unit. |
AR_SEQ_CORRELATION_FAIL |
You must enter an accounting date that is equal to or later than accounting date {MAX_GL_DATE}. |