Skip to main content

Photo Payment

With Docutain's Photo Payment SDK you can integrate photo payment into your app within minutes. It includes ready-to-use UI components that can be altered to your needs and coprorate design.

photoPayment

Data Protection

Invoices contain lots of private information that need to be protected. By using the Docutain Photo Payment SDK, you have chosen the only available solution that provides 100% data protection.

This is because all functionality, especially analyzing the document content to find the relevant payment information happens on device, 100% offline. Meaning, no data at all is transfered to any external server or cloud service.

This eliminates any data protection risk and makes the Docutain SDK the first choice.

Reliability

We all know that even the most reliable servers experience outages from time to time, which directly result in the inability to process photo payments for your users.

Since the Docutain SDK runs offline on the respective device, without any server connection, the functionality is 100% available.

Photo Payment

Initialization

Start Photo Payment

To start the photo payment process you only have to call DocutainSDK.startPhotoPayment and wait for it to return.

You can pass options to change some behaviours and theming to adopt it to your needs. See Change default scan behaviour for possible custom settings.

import { DocutainSDK } from '@docutain/capacitor-plugin-docutain-sdk'

async startPhotoPayment(){
try{
const result = await DocutainSDK.startPhotoPayment({
//customize the photo payment process according to your needs
});
if(result.data !== ""){
//payment information has been extracted
//result.data is a JSON string containing the information
//extract the fields you need and pass it on to your payment sheet
} else{
//no data was extracted at all
//Note: this case is only reachable, if you disabled the Empty Result Screen
}
} catch (error) {
if ((error as { code?: string })?.code === 'CANCELED') {
//user canceled scan process
console.log(`user canceled`);
} else {
console.error(error);
}
}
}

Extract Payment Data

The payment data will be returned as JSON string. By default, it will have the following structure:

{
"Address":
{
"Name1": "DB Fernverkehr AG",
"Name2": "",
"Name3": "",
"Zipcode": "60643",
"City": "Frankfurt am Main",
"Street": "BahnCard-Service",
"Phone": "0302970",
"CustomerId": "",
"Bank": [{"BIC": "PBNKDEFFXXX",
"IBAN": "DE02100100100152517108"}]
},
"Date": "2024-10-14",
"Amount": "244.00",
"InvoiceId": "2023174086",
"Reference": "RNr:2023174086 vom 14.10.2024",
"SEPACreditor": "DB Vertrieb GmbH"
}

If you don't need it, you can disable reading the BIC:

const result = await DocutainSDK.startPhotoPayment({ 
analyzeConfig: { readBIC: false}
});

Instead of a Bank element, the data will then only have an IBAN element:

{
"Address":
{
"Name1": "DB Fernverkehr AG",
"Name2": "",
"Name3": "",
"Zipcode": "60643",
"City": "Frankfurt am Main",
"Street": "BahnCard-Service",
"Phone": "0302970",
"CustomerId": "",
"IBAN": ["DE76570928000208303503", "DE41510500150710030316"]
},
"Date": "2024-10-14",
"Amount": "244.00",
"InvoiceId": "2023174086",
"Reference": "RNr:2023174086 vom 14.10.2024",
"SEPACreditor": "DB Vertrieb GmbH"
}

Optionally, you can enable reading the payment state, telling you whether the invoice has already been marked as paid.

const result = await DocutainSDK.startPhotoPayment({ 
analyzeConfig: { readPaymentState: true}
});

The payment data will then have an additional value PaymentState which contains either Paid or ToBePaid:

{
"Address":
{
"Name1": "DB Fernverkehr AG",
"Name2": "",
"Name3": "",
"Zipcode": "60643",
"City": "Frankfurt am Main",
"Street": "BahnCard-Service",
"Phone": "0302970",
"CustomerId": "",
"Bank": [{"BIC": "PBNKDEFFXXX",
"IBAN": "DE02100100100152517108"}]
},
"Date": "2024-10-14",
"Amount": "244.00",
"InvoiceId": "2023174086",
"Reference": "RNr:2023174086 vom 14.10.2024",
"PaymentState": "ToBePaid",
"SEPACreditor": "DB Vertrieb GmbH"
}

Onboarding

The SDK provides 2 optional onboarding possibilities that will be shown to the user on first start with some default content. You can customize it according to your needs or disable it completely.

See Onboarding for details.

onboardingDataProtection onboardingLightingConditions

Scan Tips

The SDK provides an optional toolbar item within the scanning screen, that when clicked, will open some tips on how to get the best scan result. By default it is activated and shows some default items. You can customize it according to your needs or disable it completely.

See Scan Tips for details.

scanTips

Empty Result Screen

By default, when no payment data could be extracted (meaning, no IBAN, no SEPACreditor, no Amount), the SDK provides a screen with some tips and an option to cancel or to retry the scan. You can customize it according to your needs or disable it completely.

emptyResultScreen

Disable

To disable the empty result screen, set the emptyResultScreen option to null:

const result = await DocutainSDK.startPhotoPayment({ 
emptyResultScreen:null
});

Customize

Button colors are configured by the global color configuration.

If you want to provide your own items instead of the default items, you can do that by providing your own list of DocutainListItem. Each item consists of an image, a title and a message.

const result = await DocutainSDK.startPhotoPayment({ 
emptyResultScreen:{
items: [
{image:"my_icon", title:"my item 1", message:"message my emptyResultScreen item 1\nline 2"},
{image:"photopayment_doc_detection_hint", title:"my item 2", message:"message my emptyResultScreen item 2\nline 2"},
]
}
});

The following provides an overview of the currently available options to alter the emptyResultScreen:

PropertyTypeDescription
itemsDocutainListItem[]The items you want to show as scan tips. If you don't provide any items, some default items will be displayed.
titlestringThe title to be displayed in the top toolbar.
repeatButtonDocutainButtonThe button that restarts the scan process.
info

You can get the default items used by the SDK to use them for your own list.

const emptyResultScreenDefaultItems = (await DocutainSDK.emptyResultScreenDefaultItems()).items;

The following sample alters the repeatButton:

const result = await DocutainSDK.startPhotoPayment({
emptyResultScreen:{
repeatButton: {title:"my repeat button"}
}
});

Change default scan behaviour

PhotoPaymentConfiguration

You can use the StartPhotoPaymentOptions to alter the default scan behaviour to your needs. Currently the following values can be set:

PropertyTypeDefault ValueDescription
allowCaptureModeSettingbooleanfalseIf true, the document scanner toolbar will display an item that allows the user to switch between automatic and manual camera triggering.
autoCapturebooleantrueIf true, the camera will capture the image automatically at the right moment.
defaultScanFilterScanFilterIllustrationThe default scan filter that will be used after scan.
pageEditConfigPageEditConfigurationPageEditConfigurationConfiguration class used to alter the default page editing behaviour. See PageEditConfiguration for more details.
sourceSourceCameraImportThe source of the Document Scanner.
sourceImagesstring[]nullThe source images for the document scanner if you have set the source to Image.
autoCropbooleanfalseIf true, image gets automatically cropped if document was detected. This applies only when importing images.
multiPagebooleantrueIf true, scanning multi page documents is possible. Set this to false if you need to scan single page documents.
preCaptureFocusbooleantrueIf true, the camera will run a focus action right before taking the image. This improves the quality of the scanned images, but depending on the device, image capture might take a little bit longer. Available only on Android.
textConfigTextConfigurationTextConfigurationConfiguration class used to alter the default text behaviour. See TextConfiguration for more details.
buttonConfigButtonConfigurationButtonConfigurationConfiguration class used to alter the default buttons. See ButtonConfiguration for more details.
ColorConfigColorConfigColorConfigConfiguration class used to alter the default color theming behaviour. See Color Configuration for more details.
confirmPagesbooleanfalseIf true, a list of all pages (thumbnails) will be displayed before the scan process can be finished.
allowPageEditingbooleantrueIf true, after the scan screen is finished, an editing screen with the captured images will be displayed. On the editing screen, the user can crop manually, rotate the page, filter the page and much more. The editing screen can be configured by accessing the PageEditConfiguration.
statusBarAppearanceStatusBarAppearancenullOverrides the status bar appearance. By default, the system chooses the appearance based on the current UI Mode. This only applies to Android.
navigationBarAppearanceNavigationBarAppearancenullOverrides the navigation bar appearance. By default, the system chooses the appearance based on the current UI Mode. This only applies to Android.
onboardingOnboarding?OnboardingAn optional onboarding when the user opens the scanner for the first time. See Onboarding for more details.
scanTipsScanTips?ScanTipsAn optional toolbar item that shows scan tips when clicked. See ScanTips for more details.
analyzeConfigPaymentAnalyzeConfigurationPaymentAnalyzeConfigurationA configuration class used to alter the default document analysis behaviour for payment. See Extract Payment Data for more details.
vibrateOnCapturebooleantrueIf true, when an image is captured, the device vibrates to signal successful capture.
emptyResultScreenEmptyResultScreen?EmptyResultScreenA screen that will be displayed if no payment information could be extracted. See Empty Result Screen for more details.
info

All parameters in PhotoPaymentConfiguration are optional.


The following sample shows how to disable page editing completely:

const result = await DocutainSDK.startPhotoPayment({
allowPageEditing: false
});

PageEditConfiguration

You can use the PageEditConfiguration to alter the default page editing behaviour of the document scanner to your needs. Currently the following values can be set:

PropertyTypeDefault ValueDescription
allowPageFilterbooleanfalseIf false, the bottom toolbar will hide the filter page item.
allowPageRotationbooleanfalseIf false, the bottom toolbar will hide the rotate page item.
allowPageArrangementbooleanfalseIf false, the bottom toolbar will hide the arrange page item.
allowPageCroppingbooleantrueIf false, the bottom toolbar will hide the page cropping item.
allowPageRetakebooleantrueIf true, the bottom toolbar will show a button allowing to retake the current page.
allowPageAddbooleantrueIf true, the bottom toolbar will show a button allowing to add a new page.
allowPageDeletionbooleantrueIf true, the menu item for deleting pages will be displayed in the toolbar.
pageArrangementShowDeleteButtonbooleanfalseIf true, each item of the page arrangement functionality will show a delete button.
pageArrangementShowPageNumberbooleantrueIf true, each item of the page arrangement functionality will show it's page number.
info

All parameters in PageEditConfiguration are optional.


The following sample shows how to disable the page retake button:

const result = await DocutainSDK.startPhotoPayment({
pageEditConfig : {
allowPageRetake: false
}
});

TextConfiguration

You can use the TextConfiguration to alter the default text behaviour of the document scanner to your needs. If a value does not get set explicitly, the default value provided by the SDK will be used. If you set a text value to null, it won't show any text. You can use this to remove predefined text. Currently the following values can be set:

PropertyTypeDescription
textSizeBottomToolbarnumberThe text size of elements residing in the bottom toolbar.
textSizeTopToolbarnumberThe text size of menu items residing in the top toolbar.
textSizeScanButtonsnumberThe text size of the buttons in the scan page, located at the lower part, like the torch button.
textSizeTitlenumberThe text size of the title in the top toolbar. By default, auto shrinking down till 9.0 is enabled. If you define your custom size, automatic shrinking will be disabled.
textTitleScanPagestringThe title to be displayed in the scan page top toolbar.
textTitleEditPagestringThe title to be displayed in the edit page top toolbar.
textTitleFilterPagestringThe title to be displayed in the filter page top toolbar.
textTitleCroppingPagestringThe title to be displayed in the cropping page top toolbar.
textTitleArrangementPagestringThe title to be displayed in the page arrangement page top toolbar.
textTitleConfirmationPagestringThe title to be displayed in the confirmation page top toolbar.
textDocumentTitlestringThe title to show in the top toolbar on all pages. It overwrites page specific titles, if any are set.
textFocusHintstringThe text to show when camera is focusing after capture got triggered.
textFirstPageHintstringThe text to show when user swipes to previous page but is already at the first page.
textLastPageHintstringThe text to show when user swipes to next page but is already at the last page.
textOnePageHintstringThe text to show when user swipes to next or previous page but only one page is available.
textScanProgressstringThe text to show in the progress popup that is shown when user clicks the done button but some pages still need to be processed.
textDeleteDialogCurrentPagestringThe text to show for the option to delete the current page within the dialog that will be shown when clicking delete while multiple pages are available.
textDeleteDialogAllPagesstringThe text to show for the option to delete all pages within the dialog that will be shown when clicking delete while multiple pages are available.
textDeleteDialogCancelstringThe text to show for the option to cancel within the dialog that will be shown when clicking delete while multiple pages are available.
info

All parameters in TextConfiguration are optional.


The following sample shows how to set a document title:

const result = await DocutainSDK.startPhotoPayment({
textConfig : {
textDocumentTitle: "my Document Title"
}
});

ButtonConfiguration

You can use the ButtonConfiguration to alter the default buttons of the scanner. Each button is an object of DocutainButton and has a title and icon property. Buttons residing in the top toolbar can have either a title or an icon. If you define both, the icon will be displayed. Buttons residing in the bottom toolbar can have both title and icon at the same time. If you want a button to only display text, set the icon property to null and the title property to the text you want to display. If you want a button to only display an icon, set the title property to null and the icon property to the icon you want to display. icon needs to be a name of an image resource in the drawable folder (Android), respectively the name of an image in your assets catalog (iOS).

Currently the following buttons can be set:

ButtonDefault ValueDescription
buttonEditRotatebuttonEditRotateThe button that rotates the current page.
buttonEditCropbuttonEditCropThe button that opens the cropping functionality.
buttonEditFilterbuttonEditFilterThe button that opens the filter functionality.
buttonEditArrangebuttonEditArrangeThe button that opens the page arrangement functionality.
buttonEditRetakebuttonEditRetakeThe button that starts the process of replacing the current page with a new scan.
buttonEditAddPagebuttonEditAddPageThe button on the edit page that opens the scan screen to add a new page.
buttonEditDeletebuttonEditDeleteThe button that deletes the current page or opens a dialog with options if multiple pages are available.
buttonEditFinishbuttonEditFinishThe button that finishes the scan process.
buttonCropExpandbuttonCropExpandThe button within the cropping functionality that expands the current cropping rectangle to the whole page.
buttonCropSnapbuttonCropSnapThe button within the cropping functionality that snaps the current cropping rectangle to the detected document.
buttonCropFinishbuttonCropFinishThe button within the cropping functionality that finishes the manual cropping process according to the current cropping rectangle.
buttonScanAutoCaptureOnbuttonScanAutoCaptureOnThe button within the scan functionality that is shown when automatic capture is activated.
buttonScanAutoCaptureOffbuttonScanAutoCaptureOffThe button within the scan functionality that is shown when automatic capture is deactivated.
buttonScanTorchbuttonScanTorchThe button within the scan functionality that toggles the torch.
buttonScanCapturebuttonScanCaptureThe button within the scan functionality that triggers a manual image capture.
buttonScanFinishbuttonScanFinishThe button within the scan functionality that finishes the current scan process and leads to the editing page.
buttonScanImportbuttonScanImportThe button on the scan page that opens a file importer.
buttonConfirmationFinishbuttonConfirmationFinishThe button on the confirmation page that finishes the scan process.
info

All parameters in ButtonConfiguration are optional.


The following sample shows how to customize the buttonEditRetake:

const result = await DocutainSDK.startPhotoPayment({
buttonConfig : {
buttonEditRetake : {title : "Custom Title", icon: "my_icon" }
}
});

ColorConfiguration

In order to fit the Docutain Photo Payment SDK into your corporate design, you have a bunch of options to alter the default color theming of the ready to use UI components. See color configuration for details.